To design a Hypermedia API

GET /hypermedia-design

HTTP/1.1 302 Found

Location: http://absynthmind.github.io/hypermedia-design/

Content-type: presentation/reveal+css

context

The rest of REST

http://tessel.io

http://martinfowler.com/articles/richardsonMaturityModel.html

“REST is software design on the scale of decades:

every detail is intended to promote software longevity and independent evolution”

“Many of the constraints
are directly opposed
to short-term efficiency.

people are fairly
good at short-term design, and usually
awful at long-term design”

Design on the scale of decades

Design on the scale of decades

Design on the scale of decades

context

Examples

https://api.github.com

							
curl -i https://api.github.com
HTTP/1.1 200 OK
Server: GitHub.com
Content-Type: application/json; charset=utf-8
Status: 200 OK

{
  "current_user_url": "https://api.github.com/user",
  "authorizations_url": "https://api.github.com/authorizations",
  "repository_url": "https://api.github.com/repos/{owner}/{repo}",
  ...
}

							
curl -i https://api.github.com/repos/absynthmind/hypermedia-design
HTTP/1.1 200 OK
Server: GitHub.com
Content-Type: application/json; charset=utf-8
Status: 200 OK

{
  "id": 15635201,
  "name": "hypermedia-design",
  "full_name": "absynthmind/hypermedia-design",
  "owner": {
    "login": "absynthmind",
    "id": 727855,
    "avatar_url": "https://gravatar.com/avatar/...",
    "followers_url": "https://api.github.com/users/absynthmind/followers",
    ...
  },
  "git_refs_url": "https://api.github.com/repos/absynthmind/hypermedia-design/git/refs{/sha}",
  "git_commits_url": "https://api.github.com/repos/absynthmind/hypermedia-design/git/commits{/sha}",
  ...
}

							
curl -i https://api.github.com/repos/absynthmind/hypermedia-design/git/refs
HTTP/1.1 200 OK
Server: GitHub.com
Content-Type: application/json; charset=utf-8
Status: 200 OK

[
  {
	...
  },
  {
    "ref": "refs/heads/master",
    "url": "https://api.github.com/repos/absynthmind/hypermedia-design/git/refs/heads/master",
    "object": {
      "sha": "b3b2d4d5b7362635c670d7f2033d9c1dc17b1416",
      "type": "commit",
      "url": "https://api.github.com/repos/absynthmind/hypermedia-design/git/commits/b3b2d4d5b7362635c670d7f2033d9c1dc17b1416"
    }
  }
]

							
curl -i https://api.github.com/repos/absynthmind/hypermedia-design/git/commits/b3b2d4d5b7362635c670d7f2033d9c1dc17b1416
HTTP/1.1 200 OK
Server: GitHub.com
Content-Type: application/json; charset=utf-8
Status: 200 OK

{
  "committer": {
    "name": "Ronk",
    "email": "ron.kersic@gmail.com",
    "date": "2014-01-13T10:39:22Z"
  },
  "message": "added introduction section",
  "parents": [
    {
      "sha": "8cfcb1d88e1546da9a3fd7407c96ad66d6325e78",
      "url": "https://api.github.com/repos/absynthmind/hypermedia-design/git/commits/8cfcb1d88e1546da9a3fd7407c96ad66d6325e78",
      "html_url": "https://github.com/absynthmind/hypermedia-design/commits/8cfcb1d88e1546da9a3fd7407c96ad66d6325e78"
    }
  ]
}

							
var api = require('traverson').json.from('https://api.github.com/')

api.newRequest()
	.follow('repository_url', 'commits_url')
	.withTemplateParameters({
	    owner: 'absynthmind',
	    repo:'hypermedia-design',
	    sha: 'b3b2d4d5b7362635c670d7f2033d9c1dc17b1416'
	}).getResource(function(err, resource) {
          if (err) { console.log(err); return; }
          console.log(resource)
	})

http://haltalk.herokuapp.com

							
GET http://api.alttekpub.com

{
  "_links": {
    "self": { "href": "..." },
    "productions": { "href": "..." }
  }
}

							
{
  "_links": {
      "self": { "href": "..." },
      "filter": { "href": "...{?categories}" } 
  },
  "categories": ["Microsoft", "Ruby", "Javascript", "Mobile"],
  "_embedded": {
       "videos": [{
         "_links": {
           "self": { "href": "..." },
           "episodes": { "href": "..." }
         },
         "title": "Real World ASP.NET MVC3",
         "description": "In this advanced, somewhat-opinionated production you'll get your very own startup off the ground using ASP.NET MVC 3...",
         "permitted": true
       },
    ...
    }]
  }
}

							
{
  "_links": {
    "self": { "href": "..." }
  },
  "title": "Real World ASP.NET MVC3",
  "description": "In this advanced, somewhat-opinionated production you'll get your very own startup off the ground using ASP.NET MVC 3...",
  "permitted": true,
  "_embedded": {
    "episodes": [{
      "_links": {
        "self": { "href": "..." },
        "media": [{
          "type": "video/webm; codecs='vp8.0, vorbis'",
          "href": "..."
        },{
          "type": "video/ogg; codecs='theora, vorbis'",
          "href": "..."
        }] 
    },
    ...

Hypermedia

“the simultaneous presentation of
information and controls

such that

the information becomes the affordance through which the (client) obtains
choices and selects actions”

Coupling is the enemy

Assumptions are the
mother of all evil

Pledge to not breaking clients

							
{
  "resources": {
    "core": {
      "limit": 60,
      "remaining": 58,
      "reset": 1389681064
    },
    "search": {
      "limit": 5,
      "remaining": 5,
      "reset": 1389677567
    }
  },
  "rate": {
    "limit": 60,
    "remaining": 58,
    "reset": 1389681064
  }
}

https://api.github.com/rate_limit

Design

Approach

Five Steps

Evaluate business processes
Create state machine
Evaluate media types
Create media types
Build

Evaluate business processes

Job-to-be-Done thinking

“People don't want a 1/4'' drill
They want a 1/4'' hole”

The journey of the user through the different touchpoints that afford and characterise her interactions

Touchpoint /ˈtʌtʃpɔɪnt/

a point of interaction involving a specific need in a specific time and place

A channel is a medium of interaction with customers or users

A great API
understands its audience

Create state machine

http://amundsen.com/examples/mazes/2d/five-by-five/

cf. Restful Web APIs, Richardson et. al.

Evaluate media types

or create them

HAL
Collection+
Siren
Atom, Atom Pub
XHTML

Build

Resources are not storage items
Do not mix connectors and components

If you insist...

A monolith, once upon a time

The monolith's antidote(?)

And now what..?

Do Web right
Do HTTP right

Supernova@ING.nl

GET /hypermedia-design

The rest of REST

“REST is software design on the scale of decades:

every detail is intended to promote software longevity and independent evolution”

“Many of the constraintsare directly opposedto short-term efficiency.

people are fairly good at short-term design, and usually awful at long-term design”

Design on the scale of decades

Design on the scale of decades

Design on the scale of decades

Examples

https://api.github.com

http://haltalk.herokuapp.com

Hypermedia

“the simultaneous presentation ofinformation and controls

such that

the information becomes the affordance through which the (client) obtainschoices and selects actions”

Coupling is the enemy

Assumptions are themother of all evil

Pledge to not breaking clients

Approach

Five Steps

Evaluate business processes

Job-to-be-Done thinking

The journey of the user through the different touchpoints that afford and characterise her interactions

Touchpoint /ˈtʌtʃpɔɪnt/

a point of interaction involving a specific need in a specific time and place

A channel is a medium of interaction with customers or users

A great APIunderstands its audience

Create state machine

Evaluate media types

HAL

Collection+

Siren

Atom, Atom Pub

XHTML

Build

Resources are not storage items

Do not mix connectors and components

If you insist...

The monolith's antidote(?)

And now what..?

Do Web right

Do HTTP right

Supernova@ING.nl

“Many of the constraints
are directly opposed
to short-term efficiency.

people are fairly
good at short-term design, and usually
awful at long-term design”

“the simultaneous presentation of
information and controls

the information becomes the affordance through which the (client) obtains
choices and selects actions”

Assumptions are the
mother of all evil

A great API
understands its audience