1. Hypermedia API
Pavel Mitin
2012 Anadea Inc.

2. Why does it matter
API, API, API, API, API, API, API, API, API, API,
API, API, API, API, API, API, API, API, API, API,
API, API, API, API, API, API, API, API, API, API,
API, API, API, API, API, API, API, API, API, API,
API, API, API, API, API, API, API, API, API, API,
API, API, API, API, API, API, API, API, API, API,
API, API, API, API, API, API, API, API, API, API,
API, API, API, API, API, API, API, API, API, API,
API, API, API, API, API, API, API, API, API, API,
API, API, API, API, API, API, API, API, API, API..

3. Problem
Existing APIs are often:
● unclear
● fragile
● not extendable

4. Possible solution
“WWW is fundamentally a distributed
hypermedia application.” Richard Taylor

5. Possible solution
“WWW is fundamentally a distributed
hypermedia application.” Richard Taylor
And the application works!

6. How WEB works
Browsers know how to:
● deal with media types (text/html,
image/png...)
● navigate via links and submit forms

7. How WEB works
Browsers know how to:
● deal with media types (text/html,
image/png...)
● navigate via links and submit forms
Let’s follow the example!!!

8. Example -- eBay API
GET .../item/180881974947
{
"name" : "Monty Python and the Holy Grail white rabbit big pointy teeth",
"id" : "180881974947",
...
"links" : [
{ “type: "application/vnd.ebay.item",
"rel": "Add item to watchlist",
"href": "https://.../user/12345678/watchlist/180881974947"},
{ // and a whole lot of other operations ]}
Source: http://www.slideshare.net/josdirksen/rest-from-get-to-hateoas

9. Media types
● application/atom+xml
● image/jpeg
● audio/vnd.wave
● application/vnd.buyfolio.listing+json

10. Hypermedia links
● Embed Links
○ <img src="..." />
○ <x:include href"..." />

11. Hypermedia links
● Embed Links
○ <img src="..." />
○ <x:include href"..." />
● Outbound Links
○ <a href="..." target="_blank">...</a>

12. Hypermedia links
● Embed Links
○ <img src="..." />
○ <x:include href"..." />
● Outbound Links
○ <a href="..." target="_blank">...</a>
● Templated Links
○ <form method="get" action="...">...</form>
○ <link href="http://www.example.org/?search={search}" />

13. Hypermedia links
● Embed Links
○ <img src="..." />
○ <x:include href"..." />
● Outbound Links
○ <a href="..." target="_blank">...</a>
● Templated Links
○ <form method="get" action="...">...</form>
○ <link href="http://www.example.org/?search={search}" />
● Idempotent Links
○ <link rel="edit" href="http://example.org/edit/1"/>
○ (new XMLHttpRequest()).open("DELETE", "/tags/"+id);

14. Hypermedia links
● Embed Links
○ <img src="..." />
○ <x:include href"..." />
● Outbound Links
○ <a href="..." target="_blank">...</a>
● Templated Links
○ <form method="get" action="...">...</form>
○ <link href="http://www.example.org/?search={search}" />
● Idempotent Links
○ <link rel="edit" href="http://example.org/edit/1"/>
○ (new XMLHttpRequest()).open("DELETE", "/tags/"+id);
● Non-Idempotent Links
○ <form method="post" action="...">...</form>

15. Hypermedia Design Elements
1. Base Format
2. State Transfer
3. Domain Style
4. Application Flow

16. Base format
1. JSON
2. XML
3. XHTML/HTML5
4. Others (YAML, CSV, Markdown, Protocol
Buffers)

17. State Transfer (client-initiated)
1. None (i.e. read-only)
2. Predefined (via external documentation)
3. Ad-Hoc (via in-message hypermedia
controls)

18. Domain Style
1. Specific
2. General
3. Agnostic

19. Domain Style
<!-- domain-specific design -->
<story>
<id>...</id>
<estimate>...</estimate>
</story>

20. Domain Style
/* domain-general design */
{
"collection" : {
"items" : {
{ "key" : "id",
"value" : "12345" }
...

21. Domain Style
<!-- domain-agnostic design -->
<ul class="order">
<li class="id">...</li>
<ul class="shipping-address">
<li class="street-address">...</li>
...

22. I haven't mentioned
● Resources
● Http verbs
● Http status codes

23. Surfing your API
Source: Building Hypermedia APIs with HTML5 and Node by Mike Amundsen

24. XHTML as a base format
● Native support for links and forms
● Ubiquitous client (browser)
● XHTML is XML
● HAML :)

25. Extending vs versioning
Reasons for a new version:
● A change that alters the meaning or
functionality of an existing feature or
element
● A change that causes an existing element to
disappear or become disallowed
● A change that converts an optional element
into a required element

26. Javascript RIA
;)

27. Criticism
Usually compared to "traditional" REST API

28. Criticism
● Overcomplicated client
● Extra traffic

29. Rails and HATEOAS
● lack of abstractions for hypermedia controls

30. Rails and HATEOAS
● lack of abstractions for hypermedia controls
● confusing terms:
○ #resource are two different resources

31. Rails and HATEOAS
● lack of abstractions for hypermedia controls
● confusing terms:
○ #resource are three different resources
● OPTIONS verb

32. Rails and HATEOAS
● lack of abstractions for hypermedia controls
● confusing terms:
○ #resource are three different resources
● OPTIONS verb
● PATCH verb

33. Rails and HATEOAS
● lack of abstractions for hypermedia controls
● confusing terms:
○ #resource are three different resources
● OPTIONS verb
● PATCH verb
● PUT verb
○ upsert
○ whole resource state

34. Rails and HATEOAS
● lack of abstractions for hypermedia controls
● confusing terms:
○ #resource are three different resources
● OPTIONS verb
● PATCH verb
● PUT verb
○ upsert
○ whole resource state
● custom media types require custom code

35. Richardson Maturity Model
Source: http://martinfowler.com/articles/richardsonMaturityModel.html

36. Books