Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

HATEOAS: The Confusing Bit from REST


Published on

Published in: Technology
  • Also, I wonder about the payment link, for my unserstanding, that is. The Embedded link in the reply shows the next possible action, yes. But doesn'jt PUTting imply modifying? No payment has yet been made, so is the payment yet created? Yes, the state has been changed internally by the server, so that may be justification by itself..

    But would the POSTING to the URL of /orders/1234/payment be more logical, withh or even without money?

    Your example is a really good one. I think there's more to be learned, for me anyway, by studying this, exchanging comments.
    Are you sure you want to  Yes  No
    Your message goes here
  • I think that you should have shown DELETE as an option after the order had gone through the original POST transition.

    OTHEWISE, I wll be sharing this to lots of people. FINALLY, a theory presntation with a usalbe example of how to keep the state in the server and therefore make REST be stateless in the protocol and the client.
    Are you sure you want to  Yes  No
    Your message goes here

HATEOAS: The Confusing Bit from REST

  1. 1. HATEOAS: The Confusing Bit from REST Dr. Jim Webber
  2. 2. whoami •  PhD in parallel computing –  Speciality in programming language design(!) •  {developer, architect, director} with ThoughtWorks •  Author of “Developing Enterprise Web Services” –  And currently engaged in writing a book on Web-as-middleware
  3. 3. Roadmap •  The Richardson Maturity Model •  Hypermedia Formats •  HATEOAS – Hypermedia As The Engine Of Application State •  Semantics •  A Simple RESTful Service •  Cheap sales-pitch for our book
  4. 4. The Richardson Maturity Model •  Level 0 –  SOAP, XML RPC, POX –  Single URI Hypermedia •  Level 1 –  URI Tunnelling –  Many URIs, Single verb •  Level 2 HTTP –  Many URIs, many verbs –  CRUD services (e.g. Amazon S3) •  Level 3 URI –  Level 2 + Hypermedia –  RESTful Services
  5. 5. Why the Web? Why be RESTful? •  Scalable •  Fault-tolerant •  Recoverable •  Secure •  Loosely coupled •  Precisely the same characteristics we want in business software systems!
  6. 6. Media Types Rule! •  The Web’s contracts are expressed in terms of media types –  If you know the type, you can process the content •  Some types are special because they work in harmony with the Web –  We call these “hypermedia formats”
  7. 7. Other Resource Representations •  Remember, XML is not the only way a resource can be serialised –  Remember the Web is based on REpresentational State Transfer •  The choice of representation is left to the implementer –  Can be a standard registered media type –  Or something else •  But there is a division on the Web between two families –  Hypermedia formats •  Formats which host URIs and links –  Regular formats •  Which don’t
  8. 8. Plain Old XML is not Hypermedia Friendly HTTP/1.1 200 OK Where are the links? Content-Length: 227 Where’s the protocol? Content-Type: application/xml Date: Wed, 19 Nov 2008 21:48:10 GMT <order xmlns=""> <location>takeAway</location> <items> <item> <name>latte</name> <quantity>1</quantity> <milk>whole</milk> <size>small</size> </item> </items> <status>pending</pending> </order>
  9. 9. So what? •  How do you know the next thing to do? •  How do you know the resources you’re meant to interact with next? •  In short, how do you know the service’s protocol? –  Turn to WADL? Yuck! –  Read the documentation? Come on! –  URI Templates? Tight Coupling!
  10. 10. URI Templates are NOT a Hypermedia Substitute •  Often URI templates are used to advertise all resources a service hosts –  Do we really need to advertise them all? •  This is verbose •  This is out-of-band communication •  This encourages tight-coupling to resources through their URI template •  This has the opportunity to cause trouble! –  Knowledge of “deep” URIs is baked into consuming programs –  Services encapsulation is weak and consumers will program to it –  Service will change its implementation and break consumers
  11. 11. application/xml is not the media type you’re looking for •  Remember that HTTP is an application protocol –  Headers and representations are intertwined –  Headers set processing context for representations –  Unlike SOAP which can safely ignore HTTP headers •  It has its own header model •  Remember that application/xml has a particular processing model –  Which doesn’t include understanding the semantics of links •  Remember if a representation is declared in the Content- Type header, you must treat it that way –  HTTP is an application protocol – did you forget already?  •  We need real hypermedia formats!
  12. 12. Hypermedia Formats •  Standard –  Wide “reach” –  Software agents already know how to process them –  But sometimes need to be shoe-horned •  Self-created –  Can craft specifically for domain –  Semantically rich –  But lack reach
  13. 13. Two Common Hypermedia Formats: XHTML and ATOM •  Both are commonplace today •  Both are hypermedia formats –  They contain links •  Both have a processing model that explicitly supports links •  Which means both can describe protocols…
  14. 14. application/vnd.restbucks+xml •  What a mouthful! •  The vnd namespace is for proprietary media types –  As opposed to the IANA-registered ones •  Restbucks own XML is a hybrid –  We use plain old XML to convey information –  And link elements to convey protocol •  This is important, since it allows us to create RESTful, hypermedia aware services
  15. 15. Interlude: Microformats •  Microformats are an example of little “s” semantics •  Innovation at the edges of the Web –  Not by some central design authority (e.g. W3C) •  Started by embedding machine-processable elements in Web pages –  E.g. Calendar information, contact information, etc –  Using existing HTML features like class, rel, etc
  16. 16. Semantic versus semantic •  Semantic Web is top-down –  Driven by the W3C with extensive array of technology, standards, committees, etc –  Has not currently proven as scalable as the visionaries hoped •  RDF tripples have been harvested and processed in private databases •  Microformats are bottom-up –  Little formal organisation, no guarantee of interoperability –  Popular formats tend to be adopted (e.g. hCard) –  Easy to use and extend for our systems –  Trivial to integrate into current and future programmatic Web systems
  17. 17. Microformats and Resources •  Use Microformats to structure resources where formats exist –  I.e. Use hCard for contacts, hCalendar for data •  Create your own formats (sparingly) in other places –  Annotating links is a good start –  <link rel="" .../> –  <link rel="" type="application/atom+xml" href="{post-uri}" title="some title"> •  The rel attribute describes the semantics of the referred resource
  18. 18. Revisiting Resource Lifetime •  On the Web, the lifecycle of a single resource is more than: –  Creation –  Updating –  Reading –  Deleting •  Can also get metadata –  About the resource –  About its (subset of) the verbs it understands •  And as we see, resources tell us about other resources we might want to interact with…
  19. 19. Links •  Connectedness is good in Web-based systems •  Resource representations can contain other URIs •  Links act as state transitions •  Application (conversation) state is captured in terms of these states
  20. 20. Describing Contracts with Links •  The value of the Web is its “linked-ness” –  Links on a Web page constitute a contractfor page traversals •  The same is true of the programmatic Web •  Use Links to describe state transitions in programmatic Web services –  By navigating resources you change application state •  Hypermedia formats support this –  Allow us to describe higher-order protocols which sit comfortably atop HTTP –  Hence application/vnd.restbucks+xml
  21. 21. Links are State Transitions
  22. 22. Links as APIs <confirm xmlns="..."> •  Following a link <link rel="payment" href="https://pay" causes an action to type="application/xml"/> occur <link rel="postpone" •  This is the start of a href="https://wishlist" state machine! type="application/xml"/> </confirm> •  Links lead to other resources which also have links •  Can make this stronger with semantics –  Microformats
  23. 23. We have a framework! •  The Web gives us a processing and metadata model –  Verbs and status codes –  Headers •  Gives us metadata contracts or Web “APIs” –  URI Templates –  Links •  Strengthened with semantics –  Little “s”
  24. 24. Workflow •  How does a typical enterprise workflow look when it’s implemented in a Web-friendly way? •  Let’s take Starbuck’s as an example, the happy path is: –  Make selection •  Add any specialities –  Pay –  Wait for a while –  Collect drink
  25. 25. Workflow and MOM •  With Web Services we exchange messages with the service •  Resource state is hidden from view •  Conversation state is all we know –  Advertise it with SSDL, BPEL •  Uniform interface, roles defined by SOAP –  No “operations”
  26. 26. Hypermedia Describes Protocols! •  Links declare next valid steps •  Following links and interacting with resources changes application state •  Media types with links define contracts –  Media type defines processing model –  Links (with microformats) describe state transistions •  Don’t need a static contract description –  No WSDL, no WADL •  This is HATEOAS!
  27. 27. Web-friendly Workflow •  What happens if workflow stages are modelled as resources? •  And state transitions are modelled as hyperlinks or URI templates? •  And events modelled by traversing links and changing resource states? •  Answer: we get Web-friendly workflow –  With all the quality of service provided by the Web •  So let’s see how we order a coffee at… –  This is written up on the Web: •
  28. 28. Placing an Order •  Place your order by POSTing it to a well- known URI – Starbuck’s Service Client
  29. 29. Placing an Order: On the Wire •  Response •  Request 201 Created Location: POST /order HTTP 1.1 order/1234 Host: Content-Type: application/ Content-Length: ... vnd.restbucks+xml Content-Length: ... <order xmlns="urn:restbucks"> <drink>latte</drink> <order xmlns="urn:restbucks"> </order> <drink>latte</drink> <link rel="payment" If we have a (private) href=" A link! Is this the microformat, this can payment/order/1234" start of an API? become a neat API! type="application/xml"/> </order>
  30. 30. Whoops! A mistake •  I like my coffee to taste like coffee! •  I need another shot of espresso –  What are my OPTIONS?  Request  Response OPTIONS /order/1234 HTTP 1.1 200 OK Host: Allow: GET, PUT Phew! I can update my order, for now
  31. 31. Optional: Look Before You Leap •  See if the resource has changed since you submitted your order –  If you’re fast your drink hasn’t been prepared yet  Request  Response PUT /order/1234 HTTP 1.1 100 Continue Host: I can still PUT this Expect: 100-Continue resource, for now. (417 Expectation Failed otherwise)
  32. 32. Amending an Order •  Add specialities to you order via PUT –  Restbucks needs 2 shots! Starbuck’s Service Client
  33. 33. Amending an Order: On the Wire •  Request •  Response PUT /order/1234 HTTP 1.1 200 OK Host: Location: Content-Type: application/ order/1234 vnd.restbucks+xml Content-Type: application/ Content-Length: ... vnd.restbucks+xml Content-Length: ... <order xmlns="urn:restbucks"> <drink>latte</drink> <order xmlns="urn:restbucks"> <additions>shot</additions> <drink>latte</drink> <link rel="payment" <additions>shot</additions> href=" <link rel="payment" payment/order/1234" href=" type="application/xml"/> payment/order/1234" </order> type="application/xml"/> </order>
  34. 34. Statelessness •  Remember interactions with resources are stateless •  The resource “forgets” about you while you’re not directly interacting with it •  Which means race conditions are possible •  Use If-Unmodified-Since on a timestamp to make sure –  Or use If-Match and an ETag •  You’ll get a 412 PreconditionFailed if you lost the race –  But you’ll avoid potentially putting the resource into some inconsistent state
  35. 35. Warning: Don’t be Slow! •  Can only make changes until someone actually makes your drink –  You’re safe if you use If-Unmodified-Since or If-Match –  But resource state can change without you!   Request  Response PUT /order/1234 HTTP 1.1 Host: 409 Conflict ... Too slow! Someone else has changed the state of my order  Request  Response OPTIONS /order/1234 HTTP 1.1 Allow: GET Host:
  36. 36. Order Confirmation •  Check your order status by GETting it Starbuck’s Service Client
  37. 37. Order Confirmation: On the Wire •  Request •  Response GET /order/1234 HTTP 1.1 200 OK Host: Location: order/1234 Content-Type: application/ vnd.restbucks+xml Content-Length: ... <order xmlns="urn:restbucks"> <drink>latte</drink> <additions>shot</additions> Are they trying to tell me <link rel="payment" href="https:// something with hypermedia?" type="application/xml"/> </order>
  38. 38. Order Payment •  PUT your payment to the order resource Starbuck’s Service Client New resource!
  39. 39. How did I know to PUT? •  The client knew the URI to PUT to from the link –  PUT is also idempotent (can safely re-try) in case of failure •  Verified with OPTIONS –  Just in case you were in any doubt   Request  Response OPTIONS /payment/order/1234 HTTP 1.1 Allow: GET, PUT Host:
  40. 40. Order Payment: On the Wire •  Request •  Response PUT /payment/order/1234 HTTP 1.1 201 Created Host: Location: https:// Content-Type: application/xml Content-Length: ... 1234 Content-Type: application/xml Content-Length: ... <payment xmlns="urn:restbucks"> <cardNo>123456789</cardNo> <expires>07/07</expires> <name>John Citizen</name> <payment xmlns="urn:restbucks"> <amount>4.00</amount> <cardNo>123456789</cardNo> </payment> <expires>07/07</expires> <name>John Citizen</name> <amount>4.00</amount> </payment>
  41. 41. Check that you’ve paid •  Request •  Response GET /order/1234 HTTP 1.1 200 OK Host: Content-Type: application/ vnd.restbucks+xml Content-Length: ... My “API” has changed, because I’ve paid <order xmlns="urn:restbucks"> enough now <drink>latte</drink> <additions>shot</additions> </order>
  42. 42. Finally drink your coffee... Source:
  43. 43. Summary •  Web-based services are about state machines, and business protocols –  The HATEOAS constraint from REST •  If you don’t use hypermedia, you are NOT RESTful –  Which is OK! Good systems don’t always have to be RESTful – e.g. Amazon S3 •  Use Web for massive scalability, fault tolerance –  If you can tolerate higher latencies
  44. 44. Restbucks Written Up @ InfoQ
  45. 45. Questions? Blog: GET /Connected Jim Webber Savas Parastatidis Ian Robinson Coming 2009…