Featured talk by Senior Product Architect Matt Bishop: HATEOAS Your Cake and Eat It Too: Turning Complex Business Processes into an Easy-To-Use API We set out to build a HATEOAS server that had all the bells and whistles, only to find, well, not many pre-existing bells and whistles. By necessity we had to build our own HATEOAS server and figure out how to turn our complex ecommerce process into an API that required little training to succeed with. This talk will cover that journey and give some insight as to how to do it yourself.

2. 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

3. Overview
(very) short Level 3 definition
Level 3 Misconceptions
Developing a Level 3 API

4. 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

5. 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

6. 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

7. 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.

8. 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

9. Elastic Path’s Unicorn

11. “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

12. “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

13. 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

14. “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

15. “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

16. “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

18. 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

19. 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

20. 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

21. Connecting to Existing X
/totals/carts/27
/carts/27/lineitems /prices/carts/27
/carts/27
Cart orders/2/deliveries
Service

22. 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

23. Example: Item
assets
add to
cart prices
form
item
selections definition
availability

24. 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

25. 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

26. Form
The Government got it right
GET a /form
Fill it in
POST it to the action link

27. Selector
Like a radio button group or selection list
Set of links with choices
Each choice has:
definition
action
POST to action link

28. 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

29. Thank You All for a great
RESTFest 2012!
http://www.elasticpath.com