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