HATEOAS: The Confusing Bit from REST
20 likes9,505 views
This document discusses HATEOAS (Hypermedia as the Engine of Application State) and how it relates to RESTful web services. It introduces the Richardson maturity model for RESTful services and emphasizes that hypermedia formats are important for enabling HATEOAS. Some key hypermedia formats discussed are XHTML, Atom, and a custom XML format. The document also provides an example workflow for ordering coffee from a hypothetical RESTful service called Restbucks to illustrate how the state of an application can be driven by following hypermedia links between resources.
More Related Content
![[2018] 오픈스택 5년 운영의 경험](https://cdn.slidesharecdn.com/ss_thumbnails/cloudinfra05-190131073350-thumbnail.jpg?width=560&fit=bounds)
Similar to HATEOAS: The Confusing Bit from REST (20)
HATEOAS: The Confusing Bit from REST
- 1. HATEOAS: The Confusing Bit from REST Dr. Jim Webber http://jim.webber.name
- 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. 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. 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. Why the Web? Why be RESTful? • Scalable • Fault-tolerant • Recoverable • Secure • Loosely coupled • Precisely the same characteristics we want in business software systems!
- 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. 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. 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="http://schemas.restbucks.com/order"> <location>takeAway</location> <items> <item> <name>latte</name> <quantity>1</quantity> <milk>whole</milk> <size>small</size> </item> </items> <status>pending</pending> </order>
- 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. 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. 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. 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. 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. 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. 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. 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. 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="withdraw.cash" .../> – <link rel="service.post" type="application/atom+xml" href="{post-uri}" title="some title"> • The rel attribute describes the semantics of the referred resource
- 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. 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. 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. Links are State Transitions
- 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. 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. 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. 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. 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. 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 Restbucks.com… – This is written up on the Web: • http://www.infoq.com/articles/webber-rest-workflow
- 28. Placing an Order • Place your order by POSTing it to a well- known URI – http://example.restbucks.com/order Starbuck’s Service Client
- 29. Placing an Order: On the Wire • Response • Request 201 Created Location: http://restbucks.com/ POST /order HTTP 1.1 order/1234 Host: restbucks.com 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="https://restbucks.com/ A link! Is this the microformat, this can payment/order/1234" start of an API? become a neat API! type="application/xml"/> </order>
- 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: restbucks.com Allow: GET, PUT Phew! I can update my order, for now
- 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: restbucks.com I can still PUT this Expect: 100-Continue resource, for now. (417 Expectation Failed otherwise)
- 32. Amending an Order • Add specialities to you order via PUT – Restbucks needs 2 shots! Starbuck’s Service Client
- 33. Amending an Order: On the Wire • Request • Response PUT /order/1234 HTTP 1.1 200 OK Host: restbucks.com Location: http://restbucks.com/ 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="https://restbucks.com/ <link rel="payment" payment/order/1234" href="https://restbucks.com/ type="application/xml"/> payment/order/1234" </order> type="application/xml"/> </order>
- 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. 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: restbucks.com 409 Conflict ... Too slow! Someone else has changed the state of my order Request Response OPTIONS /order/1234 HTTP 1.1 Allow: GET Host: restbucks.com
- 36. Order Confirmation • Check your order status by GETting it Starbuck’s Service Client
- 37. Order Confirmation: On the Wire • Request • Response GET /order/1234 HTTP 1.1 200 OK Host: restbucks.com Location: http://restbucks.com/ 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? restbucks.com/payment/order/1234" type="application/xml"/> </order>
- 38. Order Payment • PUT your payment to the order resource https://restbucks.com/payment/order/1234 Starbuck’s Service Client New resource! https://restbucks.com/payment/order/1234
- 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: restbucks.com
- 40. Order Payment: On the Wire • Request • Response PUT /payment/order/1234 HTTP 1.1 201 Created Host: restbucks.com Location: https:// Content-Type: application/xml restbucks.com/payment/order/ 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. Check that you’ve paid • Request • Response GET /order/1234 HTTP 1.1 200 OK Host: restbucks.com 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. Finally drink your coffee... Source: http://images.businessweek.com/ss/06/07/top_brands/image/restbucks.jpg
- 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. Restbucks Written Up @ InfoQ http://www.infoq.com/articles/webber-rest-workflow
- 45. Questions? Blog: http://jim.webber.name GET /Connected Jim Webber Savas Parastatidis Ian Robinson Coming 2009…