Successfully reported this slideshow.

More Related Content

Related Books

Free with a 14 day trial from Scribd

See all

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…