Something Something Hypermedia APIs

Helior Colorado will elighten us with the concepts behind building Hypermedia APIs, which are really just an evolutionary approach to traditional RESTful Web Services. In this talk you'll better understand HTTP, URIs, and Hypertext, and the original intent behind these technologies. You'll also learn about such terms as HATEOAS, Hypermedia, media-types, self-descriptive APIs, affordances, out-of-band information, and more.

Video: http://www.youtube.com/watch?v=OdgVMrvfTHs

Transcript

1. Something Something Hypermedia APIs
2. Helior Colorado @helior
3. The success of the Web. • Largest platform in the world • Extendable • Future/backward compatible • High-scalability • Largely decoupled • Distributed
4. Web Services The new hawtness of the millennia
5. 2001: A Web Odyssey Architectural Styles and! the Design of Network-based Software Architectures! by Roy Fielding http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
6. REST | rest | is an architectural style consisting of a coordinated set of constraints applied to components, connectors, and data elements, within a distributed hypermedia system.
7. REST is… Defined by it’s constraints • Separation of concerns between client/server • Stateless • Cache-able • Uniform interface between components • Layered System • ….
8. Resource | ˈrēˌsôrs | is a primitive object in the web, used in the definition of its fundamental elements.
9. URI | yo͞o'är'ī | stands for Uniform Resource Identifier; is a string of characters used to identify a name of a web resource.
10. REST is an architectural style Not an ISO standard
11. Leonard Richardson Author of these fine books:
12. Richardson’s Maturity Model HTML HTTP URI
13. HTTP | āCHˈtēˈtēˈpē | stands for Hypertext Transfer Protocol; it defines how messages are formatted and transmitted, and what actions Web servers and browsers should take in response to various commands. GET /events/2013-07-14/hypermedia-apis HTTP/1.1 HOST: www.helior.info
 Accept: text/html
14. Richardson’s Maturity Model HTML HTTP URI Level 0 • One URI, one HTTP Method • XML-RPC and most of SOAP
15. Richardson’s Maturity Model HTML HTTP Level 1 • Many URIs, one HTTP method • Most “RESTful” services that aren’t URI
16. GET /events HTTP/1.1 HOST: www.helior.info Accept: application/json { "events": [ { "id": "52", "name": "Foo Event", "date": "2013-07-19" }, { "id": "56", "name": "Bar Event", "date": "2013-09-28" }, { "id": "59", "name": "Baz Event", "date": "2014-01-08" } ] }
17. Richardson’s Maturity Model HTML HTTP Level 2 • Many URIs, each supporting multiple HTTP methods URI
18. DELETE /event/52 HTTP/1.1 HOST: www.helior.info
19. Richardson’s Maturity Model Hypermedia HTTP Level 3 • Resources describe their own capabilities and interconnections URI
20. Hypermedia | hīpərˈmēdēə | applied to various media-types, it is the logical extension of hypertext, which are documents that contain references to other documents.
21. Hypermedia APIs | hīpərˈmēdēə āyˈpēˈīz | serve responses as hypermedia that manage application state. It is REST. The real REST defined in Roy Fielding’s dissertation.
22. –Tim Berners-Lee, “Weaving the Web” “In an extreme view, the world can be seen as only connections, nothing else. We think of a dictionary as the repository of meaning, but it defines words only in terms of other words. I like the idea that a piece of information is really defined only by what it’s related to, and how it’s related.”
23. Let’s talk about what you already know..
24. Sending data to a server
25. Getting to “Your Orders”
26. Accessing relevant actions
27. Managing the upgrade of a website
28. Transitioning from REST to Hypermedia is like moving the focus away from resources and into the action that you want to take place.
29. Out-of-band | outˌəvˈband | implied processing instructions that are not included within the response message of an API server. ! When they should be.
30. Like what? The context of availability, or Affordances.
31. Home List of products Product 2 Add product 2 to cart View cart Checkout Remove from cart Change quantity Managing Application State
32. Affordance | əˈfôrd-əns | is the current representation of links and controls that reflect the context of a given state, such that the user obtains choices and can select actions.
33. What else? Define how to process the content, or Media-type.
34. Examples of Media-types text/html text/css text/javascript application/json application/hal+json application/vnd.api+json application/ld+json application/rss+xml video/ogg
35. Something something media-types.
36. –Marc Andreessen, “proposed new tag: IMG” “This is required functionality for X Mosaic; we have this working, and we’ll at least be using it internally. I’m certainly open to suggestions as to how this should be handled within HTML; if you have a better idea than what I’m presenting now, please let me know. I know this is hazy wrt image format, but I don’t see an alternative than to just say “let the browser do what it can” and wait for the perfect solution to come along (MIME, someday, maybe).”
37. And finally…
38. HATEOAS | hāt-ois | is an abbreviation for Hypermedia as the Engine of Application State.
39. Clients should program against the media-type, not fixed resources.
40. Describe your API through new/existing media- types, and/or define relation names or markup that extend standard media-types.
41. Don't define fixed resource names or hierarchies; servers should instruct the client to construct URIs within link relations.
42. State transition must be driven by the client selection of server-provided choices, or affordances.
43. –Steve Klabnik, “Designing Hypermedia APIs” “Hypermedia promotes scalability, allows resilience towards future changes, and promotes decoupling and encapsulation, with all the benefits those things bring.”
44. The goal of Hypermedia is for all clients to behave like a web browser.
45. Thanks. @helior