hypermedia-design

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 constraintsare directly opposedto short-term efficiency.

people are fairlygood at short-term design, and usuallyawful at long-term design”

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 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

							{
  "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'' drillThey 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 APIunderstands 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 – Design on the scale of decades – https://api.github.com

absynthmind

GET /hypermedia-design – Design on the scale of decades – https://api.github.com

1 3 (function() { var po = document.createElement('script'); po.type = 'text/javascript'; po.async = true; po.src = 'https://apis.google.com/js/platform.js'; var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(po, s); })();

hypermedia-design

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 fairlygood at short-term design, and usuallyawful 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

1 3