Hypermedia API Pavel Mitin 2012 Anadea Inc.
Hypermedia APIPavel Mitin
2012 Anadea Inc.
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..
Problem
Existing APIs are often:● unclear● fragile● not extendable
Possible solution
“WWW is fundamentally a distributed hypermedia application.” Richard Taylor
Possible solution
“WWW is fundamentally a distributed hypermedia application.” Richard Taylor
And the application works!
How WEB works
Browsers know how to:● deal with media types (text/html,
image/png...)● navigate via links and submit forms
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!!!
Example -- eBay APIGET .../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
Media types
● application/atom+xml● image/jpeg● audio/vnd.wave● application/vnd.buyfolio.listing+json
Hypermedia links
● Embed Links○ <img src="..." />
○ <x:include href"..." />
Hypermedia links
● Embed Links○ <img src="..." />
○ <x:include href"..." />
● Outbound Links○ <a href="..." target="_blank">...</a>
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}" />
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);
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>
Hypermedia Design Elements
1. Base Format2. State Transfer3. Domain Style4. Application Flow
Base format
1. JSON2. XML3. XHTML/HTML54. Others (YAML, CSV, Markdown, Protocol
Buffers)
State Transfer (client-initiated)
1. None (i.e. read-only)2. Predefined (via external documentation)3. Ad-Hoc (via in-message hypermedia
controls)
Domain Style
1. Specific2. General3. Agnostic
Domain Style
<!-- domain-specific design -->
<story>
<id>...</id>
<estimate>...</estimate>
</story>
Domain Style
/* domain-general design */
{
"collection" : {
"items" : {
{ "key" : "id",
"value" : "12345" }
...
Domain Style
<!-- domain-agnostic design -->
<ul class="order">
<li class="id">...</li>
<ul class="shipping-address">
<li class="street-address">...</li>
...
I haven't mentioned
● Resources● Http verbs● Http status codes
Surfing your API
Source: Building Hypermedia APIs with HTML5 and Node by Mike Amundsen
XHTML as a base format
● Native support for links and forms● Ubiquitous client (browser)● XHTML is XML● HAML :)
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
Javascript RIA
;)
Criticism
Usually compared to "traditional" REST API
Criticism
● Overcomplicated client● Extra traffic
Rails and HATEOAS
● lack of abstractions for hypermedia controls
Rails and HATEOAS
● lack of abstractions for hypermedia controls● confusing terms:
○ #resource are two different resources
Rails and HATEOAS
● lack of abstractions for hypermedia controls● confusing terms:
○ #resource are three different resources ● OPTIONS verb
Rails and HATEOAS
● lack of abstractions for hypermedia controls● confusing terms:
○ #resource are three different resources ● OPTIONS verb● PATCH verb
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
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
Richardson Maturity Model
Source: http://martinfowler.com/articles/richardsonMaturityModel.html
Books