Richardson Maturity
model

0.   Swamp of Pox (RPC)

1.   Resources

2.   HTTP

3.   HATEOAS

READY.
Load HYPERDungeon

You are standing in an open field west of a white house, with a boarded front door.
There is a small mailbox here.
>

REST WITHOUT HATEOAS

Level 1

 {
     "id": 1,
     "room": "You are standing in an open field west of a white house, with a boarded front door. There is a small mailbox here."

 }

LEVEL 2

 {    
     "id": 1,
     "room": "You are standing in an open field west of a white house, with a boarded front door. There is a small mailbox here."

 }

NOW WHAT?

Hypermedia

is the web

Links

FORMs

The Humble Link

<a href="http://hyperdungeon.com" 
rel="index"
title="HyperDungeon"
data-desc="It's hyper-action in a hyper-dungeon!">HyperDungeon!</a>

FORMS

        
<form action="/action" method="post">
        
    

HATEOAS is Links

You are standing in an open field west of a white
house, with a boarded front door. 
There is a small mailbox here.

SITEmap

Level 1 & 2

Hateoas

UX for api's

"The user progresses through the application by selecting links ( state transitions ), resulting in the next page ( representing the next state of the application ) being transferred to the user and rendered." -- Roy Fielding

HATEOAS is a web interface 

(like a web page) for the application.

Designing good experience 

for a Developer (aka - The User).

Resources

Meta Information

Inheritance

• title
• rel
• href

Implied State

HyperMedia Resource

Data + Metadata

State CHANGE

You are in an open field west of a big white house with a boarded front door.
There is a small mailbox here.

> open mailbox

Opening the mailbox reveals:
A leaflet.

> look

You are in an open field west of a big white house with a boarded front door.
There is a small mailbox here.
The mailbox contains:
A leaflet. 

HATEOAS in ACtion

POST http://hyperdungeon.com/items/1

 {
    "action":"open"
 }

                            200 OK

GET http://hyperdungeon.com/items/1

 {
    "id": 1,
    "name": "small mailbox",
    "type": "container",
    "moveable": false,
    "state": "open",
    "links": [
        "contents": { "href":"http://hyperdungeon.com/items/2",...
    ] }

State ChangeD!

GET http://hyperdungeon.com/rooms/1

Errors

• Don't break the user's experience.
• Use HTTP Status Codes.
  

MAILBOx, My Mailbox

> get mailbox

An interesting idea, but...

POST http://hyperdungeon.com/item/1

 {
    "action":"get"
 }

                            403 Forbidden

 {
    "id": 1,
    "name": "small mailbox",
    "type": "container",
    "moveable": false,
    "state": "open",
    "links": [
        "contents": {"href":"http://hyperdungeon.com/items/2"},
        "self": {"href":"http://hyperdungeon.com/items/1"} ] }

RelationshipS Matter

Relationship BASICS

{
    "id": 5,
    "name": "brown sack",
    "description": "An elongated brown sack, smelling of hot peppers."
    "type": "container",
    "moveable": true,
    "state": "closed",
    "links": [
         "self": {
            "href":"http://hyperdungeon.com/items/5"
            "title": "brown sack"
         },
         "index": {
            "href":"http://hyperdungeon.com/items"
            "title": "items"
         }
     ]
}

Leverage Existing
Rel Types 

API's Outgrow
 Existing Definitions

GO DIY

vnd.company.app-version+json

Seriously. 

Write it. 

Publish it. 

Throw your specification on the pile.

Custom 

Media Types

Whole
other level

"links": {
    "http://hyperdungeon.com/directions": {
        "href": "http://hyperdungeon.com/rooms/5",
        "title": "A small forest"
    }
}

NAMESPACing

Why Namespace?

{
  "links": {























  }
}

Have Message, Will Consume

Pre-Defined
Hypermedia
Specifications

Resource Wrapper

Provides Structure

Documentation

re-Usability

Caveats

Versioning

Are Your
Users Ready?

Caching

Do you Really 

Need a Hypermedia

API? 

Documentation

Wild West

Upsurge in attention over the past 2+ years.

Change will be constant.

Media Types are going to die.

FIn

"links": {
    HTTP Status Codes,
    RFC 5988 - Rel Types
}