READY.
LOAD HYPERDUNGEON










HI



James Pozenel

Senior Software Engineer

Technical Lead on QLMS 2.0

Quicken Loans

@lectrotext @LunchBusDetroit

HyperMedia 

as The Engine 

of Application 

state

(HATEOAS)


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

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

response
Header: Status: 200 (OK) 
Body: 
 {    
     "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."

 }


Kick back, amigo.

NOW WHAT?


Hack at it?
Consult the documentation?



Hypermedia

is the web


  • state machines (HTML, CSS)
  • state transitions (link, form)
  • other stuff (img, object, script, css) - enriches the state of the application.
 


Links


 side-effect free 
state transitions

FORMs


side-effect inducing 
state transitions
 

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


  • Collection of links
  • Hierarchy

Level 1 & 2


More concerned with
  • what
  • who
  • how

Hateoas


Is concerned with:
  • why
  • when

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


Rewind

  HYPERDUNGEON api basics

     RESOURCES
    •  Rooms
    •  Items
    •  Inventory
    STATE CHANGES
    •  User can traverse the hyperdungeon 
    •  Rooms contain Items.
    •  Items can be interacted with in someway.
    •  Items and Rooms can change.
    •  Some Items can be placed in the Inventory.

Resources

Not Just the Data Object 



Meta Information


Hypermedia gives a Resource

additional properties


URI = LINK = ANCHOR tag


Inheritance

  • title
  • rel
  • href

Implied State


  • Media Type
  • Data Elements
  • Links
    • Relationship

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"
         }
     ]
}
Self and Index are universal to any Resource

Leverage Existing
Rel Types 

API's Outgrow
 Existing Definitions


Very Quickly

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?

  • Avoid Collision
  • Discoverability
{
  "links": {























  }
}

Have Message, Will Consume

 

Pre-Defined
Hypermedia
Specifications

  • Siren
  • HAL
  • Collection+JSON
  • MASON
  • Hydra (JSON-LD)
  • JSON-API

Resource Wrapper

Provides Structure


  • Link Formatting
  • Expressing Relationships
  • Actions (AKA Forms)
  • Hinting

Documentation

  • Permitted Methods
  • Permitted Actions
  • POST Body Format
  • Data Object Graphs


  • Media Type
  • JSON Schema
  • Rel Types
  • Profiles

re-Usability

Caveats


Versioning

Are Your
Users Ready?

Caching


Do you Really 

Need a Hypermedia

API? 

Documentation


  • Media Type
  • Rel Type
  • Profile
  • Schema
  • In Line (Actions, Forms)

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
}

HyperMedia

By lectrotext

HyperMedia

  • 413
Loading comments...

More from lectrotext