Matt Bishop

Product Architect at Elastic Path

Built an e-commerce HATEOAS API

18-month effort

20-person dev team

Transforming Elastic Path from Webapp-centric

to API-centric

Overview

(very) short Level 3 definition

Level 3 Misconceptions

Developing a Level 3 API

Level 3 REST (L3)

Links and Types

Not URLs (the antithesis of L3)

Not L2++

Like moving from Assembler to C

Named variables, not labeled memory addresses

Methods, not jump tables

More Who and What, less Where

REST is Mis-acronymed

Should be REality State Transfer

“Representations” are an intellectual snag that lead too quickly to type systems

L3 can only succeed when it models the real world

Most software abstractions take shortcuts:

Overload abstractions with multiple semantics

Reuse existing technical abstractions

Example: Products

What is a Product?

A Product Manager thinks of a set of options

A Customer thinks of something to put in their bag

In reality there is no such thing as a Product

Item: Something you buy and walk out with

Offering: Something that holds the possible options that lead to specific items

L3 is Hard

No HATEOAS Frameworks

All REST frameworks have Resources

None provide a way to define links between resources

L3 Clients are difficult to grok

…but not impossible. Talk to Drewz.

L3 APIs are Rare

Few Examples in the real world

“…no real facilities to support HATEOAS, a concept I feel is the unicorn of REST. Everyone thinks it’s wonderful but no one has ever actually seen it in the wild.”

–Lucis Ferre blogging about WebMachine

Elastic Path’s Unicorn

“L3 is HTTP used correctly”

HTTP is a transport protocol

L3 is an architectural style

Your server and client should be able to switch

to a different transport and succeed

“Content-Type is the Hypermedia Type”

Content-Type is an HTTP transport header

application/vnd.com.skynet.cyborg+json

…is just about as right as

application/com.warnerbrothers.featurefilm+mp4

X-Hypermedia-Type

Content-Type tells the client how the data is

serialized, not what type of data it is

Leave Content-Type to the transport layer

Put your media type in another header

Put it in your representation

“Stateless just means

Sessionless”

L3 requires one Source Of Truth

Stateless really means completely stateful

All State persisted in the backend

…not in the http session, or cookies, or client (duh)

Not in the query params either!

GET /search/books?keywords=Fear+Loathing

“Query params should pass data to a resource”

Data belongs in the representations, period

There are no universal business concepts

Example: pagination

?page=2&size=20

Resource has to understand what this means and

respond with an appropriate representation

It also may have different ways of providing pagination

“URIs should have User IDs in them”

Humans are not a resource

They own things like carts and orders and profiles

Their identity scopes their access

Authenticate them and pass their identities (and Roles) internally

BTW, anonymous users are people too

Build the Resource Model

Do NOT try to surface an existing API

Start with your existing User Interface

Use physical props

L3 works best when the resources are modeled

after the User’s experience of reality

Do this with a team, achieve unanimity

Basic Heuristics

1. A resource should have one responsibility

2. A resource has very little data and lots of links

3. “Secret Admirer” rule: A resource should not

know about the resources that link to it

Subresources

Subresources are rarely useful in L3

/carts/id/lineitems/id

Heuristic:

Is it an inseparable concept for both?

If no, then make it a separate resource

Connecting to Existing X

Cart Service

/carts/27

/carts/27/lineitems

/totals/carts/27

/prices/carts/27

orders/2/deliveries

The Dark Side of Links

The model is mostly links between resources

Downside: Chatty Cathy API

Your framework needs to provide a way to expand

related rels into a response

Example: Item

item

assets

prices

definition

availability

selections

add to cart form

Build the Hypermedia

Controls

Workflows are a series of state transitions in your process

Add to cart

Create profile

Deliver shipment

Authorize payment

These transitions are executed via hypermedia controls

What’s a Hypermedia

Control?

A design pattern for interacting with State

Can be multiple resources providing data and

actions to the control

Single entry point into the control

Numerous links inside the control

Form

The Government got it right

GET a /form

Fill it in

POST it to the action link

Selector

Like a radio button group or selection list

Set of links with choices

Each choice has:

definition

action

POST to action link

Needinfo

Link to indicate a related resource state is

incomplete. Interpreted as a transition blocker

Link points to a control to resolve the state

Example

Deliveryinfo required on an order to actually

deliver an order

Thank You All for a great

RESTFest 2012!

http://www.elasticpath.com