Hypermedia: the confusing bit from rest

3,178 views

Published on

Published in: Technology, Education
0 Comments
6 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
3,178
On SlideShare
0
From Embeds
0
Number of Embeds
4
Actions
Shares
0
Downloads
39
Comments
0
Likes
6
Embeds 0
No embeds

No notes for slide

Hypermedia: the confusing bit from rest

  1. 1. Hypermedia: The Confusing bit from REST Jim Webber http://jim.webber.name
  2. 2. Roadmap• The Richardson Maturity Model• Hypermedia: The Confusing bit from REST – Formats, protocols, and contracts• Conclusions and Q&A
  3. 3. REST is an Architectural style suited to the Web… …but it is not mandatory
  4. 4. Richardson’s Maturity Model Hypermedia HTTP URI
  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. REST isn’t…• Just pretty URIs• Just XML or JSON• URI templates• AJAX applicationsBut you could be forgiven for thinking it is!
  7. 7. Structural versus Protocol• “Structural” REST – Domain model broken up with URIs – Lazy loading, caching over the network – Proliferation of media types?• “Protocol” REST This is where the cool kids are at – Focus on media types as contracts – Protocol state transitions – DAPs – Domain Application Protocols
  8. 8. Start with Media Types• The Web’s contracts are expressed in terms of media types – And link relations• Some types are special because they work in harmony with the Web – We call these “hypermedia formats”• Know the media type, know the contract? – If you know all pertinent link relations
  9. 9. Resource Representations• 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 registered media type – Or something else• There is a division on the Web between two families – Hypermedia formats • Formats which contain URIs and links – Regular formats • Which don’t
  10. 10. XML is not Hypermedia FriendlyHTTP/1.1 200 OK Where are the links?Content-Length: 227 Where’s the protocol?Content-Type: application/xmlDate: Wed, 19 Nov 2008 21:48:10 GMT<order xmlns="http://schemas.restbucks.com/order"> <location>takeAway</location> <item> <name>latte</name> <quantity>1</quantity> <milk>whole</milk> <size>small</size> </item> <status>pending</status></order>
  11. 11. 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!
  12. 12. URI Templates are NOT a Hypermedia Substitute• URI templates are used to advertise all resources – Do we really need to advertise them all? – Verbose, out of band• Encourages tight-coupling to resources through their URI template• Opportunity to cause trouble! – Knowledge of “deep” URIs is baked into consuming programs – Services encapsulation is weak – Service will change its implementation and break consumers
  13. 13. application/xml is not the media type you’re looking for• HTTP is an application protocol – Headers and representations are intertwined – Headers set processing context for representations• application/xml has a particular processing model – Which doesn’t include understanding the semantics of links• 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? 
  14. 14. 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
  15. 15. 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…
  16. 16. 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
  17. 17. 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
  18. 18. 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
  19. 19. Microformats and Resources• Use Microformats to structure resources where formats exist – I.e. Use hCard for contacts, hCalendar for data• Create your own formats 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
  20. 20. 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• Resources link to other resources we might want to interact with to reach an objective This is important
  21. 21. Links• Connectedness is good in Web-based systems• Resource representations can contain other URIs – Web pages anybody?• Links advertise valid state transitions in a protocol/workflow• Application (conversation) state is captured in terms of these states
  22. 22. Advertise Contracts with Links• Media types and link relations give us contracts, hypermedia puts them to work! – Contract is typically expressed as a number of media types plus link relations – “Media type composition” - Ian Robinson• Hypermedia formats are key: – Allow us to describe domain application protocols which sit comfortably atop HTTP – application/vnd.restbucks+xml – application/atom+xml• Can build DAPs atop DAPs too
  23. 23. Links are State Transitions
  24. 24. Links as APIs<confirm xmlns="..."> • Following a link causes<link rel="payment" href="https://pay" an action to occur type="application/xml"/> • This is the start of a<link rel="postpone" href="https://wishlist" state machine! type="application/xml"/> • Links lead to other</confirm> resources which also have links • Can make this stronger with semantics – Microformats
  25. 25. 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
  26. 26. Workflow and MOM• With Web Services we exchange messages with Order Drink the service Starbuck’s Service• Resource state is hidden Add Specialities from view• Conversation state is all Order Confirmation we know – Advertise it with SSDL, Pay BPEL• Uniform interface, roles Coffee! defined by SOAP – No “operations”
  27. 27. 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 transitions• Don’t need a static contract description – No WSDL, no WADL• This is HATEOAS!• So let’s see how we order a coffee at Restbucks.com… – Based on: http://www.infoq.com/articles/webber-rest-workflow
  28. 28. Hypermedia Protocols Easily Compose Services Unfollowed Link Followed Link
  29. 29. Static Interface and State Transitions
  30. 30. Place an Order• POST to a well-known URI – http://restbucks.com/order Restbucks Service Client
  31. 31. Placing an Order• RequestPOST /order HTTP/1.1Content-Type: application/vnd.restbucks+xmlAccept: application/vnd.restbucks+xmlHost: restbucks.comConnection: keep-aliveContent-Length: 278<?xml version="1.0" encoding="UTF-8" standalone="yes"?><rb:order xmlns:rb="http://schemas.restbucks.com"> <rb:item> <rb:milk>semi</rb:milk> <rb:size>large</rb:size> <rb:drink>latte</rb:drink> </rb:item> <rb:location>takeaway</rb:location></rb:order>
  32. 32. Placing an Order• ResponseHTTP/1.1 201 CreatedLocation: http://restbucks.com/order/f932f92dContent-Type: application/vnd.restbucks+xmlContent-Length: 828Date: Sun, 06 Sep 2009 06:51:22 GMT<?xml version="1.0" encoding="UTF-8" standalone="yes"?><rb:order xmlns:rb="http://schemas.restbucks.com" xmlns:dap="http://schemas.restbucks.com/dap"> <dap:link mediaType="application/vnd.restbucks+xml" uri="http://restbucks.com/order/f932f92d" rel="cancel"/> <dap:link mediaType="application/vnd.restbucks+xml" uri="http://restbucks.com/payment/f932f92d" rel="payment"/> <dap:link mediaType="application/vnd.restbucks+xml" uri="http://restbucks.com/order/f932f92d" rel="update"/> <dap:link mediaType="application/vnd.restbucks+xml" uri="http://restbucks.com/order/f932f92d" rel="latest"/> <rb:item> <rb:milk>semi</rb:milk> <rb:size>large</rb:size> <rb:drink>latte</rb:drink> </rb:item> <rb:location>takeaway</rb:location> <rb:cost>2.0</rb:cost> <rb:status>unpaid</rb:status></rb:order>
  33. 33. Confirm the Order• GET from the rel=“latest” URI – http://restbucks.com/order/f932f92d Restbucks Service Client
  34. 34. Confirm the Order• RequestGET /order/f932f92d HTTP/1.1Accept: application/vnd.restbucks+xmlHost: restbucks.comConnection: keep-alive
  35. 35. Confirm the Order• ResponseHTTP/1.1 200 OKLocation: http://restbucks.com/order/f932f92dContent-Type: application/vnd.restbucks+xmlContent-Length: 828Date: Sun, 06 Sep 2009 06:51:22 GMT<?xml version="1.0" encoding="UTF-8" standalone="yes"?><rb:order xmlns:rb="http://schemas.restbucks.com" xmlns:dap="http://schemas.restbucks.com/dap"> <dap:link mediaType="application/vnd.restbucks+xml" uri="http://restbucks.com/order/f932f92d" rel="cancel"/> <dap:link mediaType="application/vnd.restbucks+xml" uri="http://restbucks.com/payment/f932f92d" rel="payment"/> <dap:link mediaType="application/vnd.restbucks+xml" uri="http://restbucks.com/order/f932f92d" rel="update"/> <dap:link mediaType="application/vnd.restbucks+xml" uri="http://restbucks.com/order/f932f92d" rel="latest"/> <rb:item> <rb:milk>semi</rb:milk> <rb:size>large</rb:size> <rb:drink>latte</rb:drink> </rb:item> <rb:location>takeaway</rb:location> <rb:cost>2.0</rb:cost> <rb:status>unpaid</rb:status></rb:order>
  36. 36. Change the Order• POST new order to service-generated URI – http://restbucks.com/order/f932f92d Restbucks Service Client
  37. 37. POST? Not PUT?• PUT expects the whole resource state to be presented in the request – But our clients aren’t responsible for generating hypermedia links• PATCH would be better – It allows us to send diffs, but isn’t part of the standard yet• So POST is our only option – Compare this to CRUD protocols
  38. 38. Change the Order• RequestPOST order/f932f92d HTTP/1.1Content-Type: application/vnd.restbucks+xmlAccept: application/vnd.restbucks+xmlHost: restbucks.comConnection: keep-aliveContent-Length: 278<?xml version="1.0" encoding="UTF-8" standalone="yes"?><rb:order xmlns:rb="http://schemas.restbucks.com"> <rb:item> <rb:milk>semi</rb:milk> No Hypermedia <rb:size>large</rb:size> <rb:drink>cappuccino</rb:drink> Controls? </rb:item> <rb:location>takeaway</rb:location></rb:order>
  39. 39. Change the Order• ResponseHTTP/1.1 200 OKLocation: http://restbucks.com/order/f932f92dContent-Type: application/vnd.restbucks+xmlContent-Length: 828Date: Sun, 06 Sep 2009 06:52:22 GMT<?xml version="1.0" encoding="UTF-8" standalone="yes"?><rb:order xmlns:rb="http://schemas.restbucks.com" xmlns:dap="http://schemas.restbucks.com/dap"> <dap:link mediaType="application/vnd.restbucks+xml" uri="http://restbucks.com/order/f932f92d" rel="cancel"/> <dap:link mediaType="application/vnd.restbucks+xml" uri="http://restbucks.com/payment/f932f92d" rel="payment"/> <dap:link mediaType="application/vnd.restbucks+xml” uri="http://restbucks.com/order/f932f92d" rel="update"/> <dap:link mediaType="application/vnd.restbucks+xml" uri="http://restbucks.com/order/f932f92d" rel="latest"/> <rb:item> <rb:milk>semi</rb:milk> <rb:size>large</rb:size> <rb:drink>cappuccino</rb:drink> </rb:item> <rb:location>takeaway</rb:location> <rb:cost>2.0</rb:cost> <rb:status>unpaid</rb:status></rb:order>
  40. 40. What if we want to cancel?• DELETE order at order URI – http://restbucks.com/order/f932f92d Restbucks Service Client
  41. 41. What if we want to cancel?• RequestDELETE /order/f932f92d HTTP/1.1Host: restbucks.comConnection: keep-alive• ResponseHTTP/1.1 200 OKContent-Type: application/vnd.restbucks+xmlDate: Sun, 06 Sep 2009 06:53:22 GMT
  42. 42. Order Payment• PUT to service-generated payment URI – http://restbucks.com/payment/f932f92d Restbucks Service Client
  43. 43. Why PUT this time?• It’s idempotent – Safe to repeat in the event of failures• For all €/$/¥/£ transactions, prefer idempotent verbs
  44. 44. Order Payment• RequestPUT /payment/f932f92d HTTP/1.1Content-Type: application/vnd.restbucks+xmlAccept: application/vnd.restbucks+xmlHost: restbucks.comConnection: keep-aliveContent-Length: 269<?xml version="1.0" encoding="UTF-8" standalone="yes"?><payment xmlns="http://schemas.restbucks.com"> <amount>2.0</amount> <cardholderName>Michael Farraday</cardholderName> <cardNumber>11223344</cardNumber> <expiryMonth>12</expiryMonth> <expiryYear>12</expiryYear></payment>
  45. 45. Order Payment• ResponseHTTP/1.1 201 CreatedLocation: http://restbucks.com/payment/f932f92dContent-Type: application/vnd.restbucks+xmlContent-Length: 547Date: Sun, 06 Sep 2009 06:51:22 GMT<?xml version="1.0" encoding="UTF-8" standalone="yes"?><rb:payment xmlns="http://schemas.restbucks.com/dap" xmlns:rb="http://schemas.restbucks.com"> <link mediaType="application/vnd.restbucks+xml" rel="latest" uri="http://restbucks.com/order/f932f92d" /> <link mediaType="application/vnd.restbucks+xml" rel="receipt" uri="http://restbucks.com/receipt/f932f92d" /> <rb:amount>2.0</rb:amount> <rb:cardholderName>Michael Farraday</rb:cardholderName> <rb:cardNumber>11223344</rb:cardNumber> <rb:expiryMonth>12</rb:expiryMonth> <rb:expiryYear>12</rb:expiryYear></rb:payment>
  46. 46. What if we want to cancel now?• RequestDELETE /order/f932f92d HTTP/1.1Host: restbucks.comConnection: keep-alive• ResponseHTTP/1.1 405 Method Not AllowedAllow: GETContent-Type: application/vnd.restbucks+xmlContent-Length: 0Date: Sun, 06 Sep 2009 07:43:29 GMT
  47. 47. Grab a Receipt• GET service-generated receipt URI – http://restbucks.com/receipt/f932f92d Restbucks Service Client
  48. 48. Grab a Receipt• RequestGET /receipt/f932f92d HTTP/1.1Accept: application/vnd.restbucks+xmlHost: restbucks.comConnection: keep-alive
  49. 49. Grab a Receipt• RequestHTTP/1.1 200 OKContent-Type: application/vnd.restbucks+xmlContent-Length: 332Date: Sun, 06 Sep 2009 06:51:22 GMT<?xml version="1.0" encoding="UTF-8" standalone="yes"?><rb:receipt xmlns="http://schemas.restbucks.com/dap" xmlns:rb="http://schemas.restbucks.com"> <link mediaType="application/vnd.restbucks+xml" rel="order" uri="http://restbucks.com/order/f932f92d" /> <rb:amount>2.0</rb:amount> <rb:paid>2009-09-06T16:51:22.814+10:00</rb:paid></rb:receipt>
  50. 50. Complete the Order• GET from the rel=“order” URI – http://restbucks.com/order/f932f92d Restbucks Service Client
  51. 51. Complete the Order• RequestGET /order/f932f92d HTTP/1.1Host: restbucks.comConnection: keep-alive
  52. 52. Complete the Order• ResponseHTTP/1.1 200 OKContent-Type: application/vnd.restbucks+xmlContent-Length: 455<?xml version="1.0" encoding="UTF-8" standalone="yes"?><rb:order xmlns:rb="http://schemas.restbucks.com" xmlns:dap="http://schemas.restbucks.com/dap"> <dap:link mediaType="application/vnd.restbucks+xml" uri="http://restbucks.com/order/f932f92d" rel="latest"/> <rb:item> <rb:milk>semi</rb:milk> <rb:size>large</rb:size> <rb:drink>cappuccino</rb:drink> </rb:item> <rb:location>takeaway</rb:location> <rb:cost>2.0</rb:cost> <rb:status>ready</rb:status></rb:order>
  53. 53. Complete the Order• DELETE order at rel=“latest” URI – http://restbucks.com/order/f932f92d Restbucks Service Client
  54. 54. Complete the Order• RequestDELETE/order/f932f92d HTTP/1.1Host: restbucks.comConnection: keep-alive
  55. 55. Complete the Order• ResponseHTTP/1.1 200 OKContent-Type: application/vnd.restbucks+xmlContent-Length: 360Date: Sun, 06 Sep 2009 23:01:10 GMT<?xml version="1.0" encoding="UTF-8" standalone="yes"?><rb:order xmlns:rb="http://schemas.restbucks.com" xmlns:dap="http://schemas.restbucks.com/dap"> <rb:item> <rb:milk>semi</rb:milk> <rb:size>large</rb:size> <rb:drink>cappuccino</rb:drink> No Hypermedia </rb:item> Controls <rb:location>takeaway</rb:location> <rb:cost>2.0</rb:cost> <rb:status>taken</rb:status></rb:order>
  56. 56. Source: http://images.businessweek.com/ss/06/07/top_brands/image/starbucks.jpg
  57. 57. Summary• Web services are about state machines, and business protocols• Hypermedia formats and link relations are for contracts – HATEOAS extends protocols over the network• If you don’t use hypermedia, you are NOT RESTful – That’s OK, you’re still valuable, like Amazon S3!

×