REST Fest 2012: HATEOAS Your Cake and Eat It Too


Published on

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.

Published in: Technology, Business

REST Fest 2012: HATEOAS Your Cake and Eat It Too

  1. 1. 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
  2. 2. Overview (very) short Level 3 definition Level 3 Misconceptions Developing a Level 3 API
  3. 3. 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
  4. 4. 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
  5. 5. 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
  6. 6. 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.
  7. 7. 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
  8. 8. Elastic Path’s Unicorn
  9. 9. “L3 is HTTP usedcorrectly” 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
  10. 10. “Content-Type is theHypermedia Type” Content-Type is an HTTP transport header application/…is just about as right as application/com.warnerbrothers.featurefilm+mp4
  11. 11. 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
  12. 12. “Stateless just meansSessionless” 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
  13. 13. “Query params shouldpass 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
  14. 14. “URIs should have UserIDs 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
  15. 15. 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
  16. 16. Basic Heuristics1. A resource should have one responsibility2. A resource has very little data and lots of links3. “Secret Admirer” rule: A resource should not know about the resources that link to it
  17. 17. 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
  18. 18. Connecting to Existing X /totals/carts/27 /carts/27/lineitems /prices/carts/27 /carts/27 Cart orders/2/deliveries Service
  19. 19. 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
  20. 20. Example: Item assets add to cart prices form item selections definition availability
  21. 21. Build the HypermediaControls 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
  22. 22. What’s a HypermediaControl? 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
  23. 23. FormThe Government got it right GET a /form Fill it in POST it to the action link
  24. 24. Selector Like a radio button group or selection list Set of links with choices Each choice has: definition action POST to action link
  25. 25. 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
  26. 26. Thank You All for a greatRESTFest 2012!