Hypermedia APIs: The Rest of REST

Chris Marinos presents:

Hypermedia APIs: The Rest of REST

The Agenda

❖ REST overview

❖ Hypermedia

❖ Affordances

❖ Demo

Who has written or consumed a REST API?

What is REST?

–Chris Marinos

REST APIs are where you, like, follow HTTP and stuff

Representational State Transfer (REST) is a

software architecture style consisting of guidelines

and best practices for creating scalable web

services. REST is a coordinated set of constraints

applied to the design of components in a distributed

hypermedia system that can lead to a more

performant and maintainable architecture.

Representational State Transfer (REST) is a

software architecture style consisting of guidelines

and best practices for creating scalable web

services. REST is a coordinated set of constraints

applied to the design of components in a distributed

hypermedia system that can lead to a more

performant and maintainable architecture.

REST is the architectural style of the internet

REST Constraints

❖ Client-Server

❖ Stateless

❖ Cache

❖ Uniform Interface

❖ Layered System

❖ Code-On-Demand (optional)

REST Benefits

❖ Client-Server -> reuse across clients

❖ Stateless -> scalability/reliability

❖ Cache -> performance

❖ Uniform Interface -> simplicity of interaction

❖ Layered System -> visibility

❖ Code-On-Demand (optional) -> extensibility of client

No HTTP?

–Roy Fielding

“…if the engine of application state (and hence the

API) is not being driven by hypertext, then it cannot

be RESTful and cannot be a REST API. Period.”

The Agenda

❖ REST overview

❖ Hypermedia

❖ Affordances

❖ Demo

HATEOAS

Hypertext as the Engine of Application State

(also a horrible acronym)

So what is hypermedia?

Richardson Maturity Model

Level 0: Pox

Level 1: Resources

Level 2: HTTP Verbs

Level 3: Hypermedia Controls

REST

Level 0: POX

POST /myservice/

{

method: ‘get_customer’

customer_id: 1235

}

POST /myservice/

<?xml version="1.0"?>

<soap:Envelope

xmlns:soap="http://www.w3.org/2001/12/soap-envelope"

soap:encodingStyle="http://www.w3.org/2001/12/soap-

encoding">

<soap:Body xmlns:m="http://www.example.org/stock">

<m:GetCustomer>

<m:CustomerId>1234</m:CustomerId>

</m:GetCustomer>

</soap:Body>

</soap:Envelope>

Level 1: Resources

POST /customer/

{ method: ‘get_customer’, customer_id: 1234}

POST /organization/

{ method: ‘get_organization’, organization_id: 1234}

POST /organization/

{

method: ‘create_organization’,

organization_id: 1234,

name: ‘new name’

}

Level 2: Verbs

GET /organizations/

————————

{

organization_id: 1234

name: ‘Cool Stuff Inc.’

}

POST /organizations/

{

organization_id: 999

name: ‘My New Organization’

}

GET /organizations/999

————————

{

organization_id: 999

name: ‘My New Organization’

}

Level 3: Hypermedia

GET /organizations/

<form name="input" method=“post" action=“/organizations/“>

Name: <input type="text" name=“organization_name">

<input type="submit" value="Submit">

</form>

POST /organizations/

{

organization_id: 1234

name: ‘My RESTful Organization’

}

The Agenda

❖ REST overview

❖ Hypermedia

❖ Affordances

❖ Demo

“A REST API should be entered with no prior

knowledge beyond the initial URI (bookmark) and set

of standardized media types that are appropriate for

the intended audience (i.e., expected to be

understood by any client that might use the API)”

–Roy Fielding

Affordances

State transitions over URL structure

Hypermedia Benefits

• API discoverability and documentation

• Reuse of state transition logic across clients

• Ease of client development

• More flexibility for servers to evolve

Hypermedia Formats

HTML

XHTML

Collection+JSON

Siren

HAL

JSON-LD

NOT JSON or XML

Collection+JSON

{

"collection" :

{

"version" : “1.0",

"href" : “https://foo.com/api/“,

"links" : […],

"items" : […],

"queries" : […],

"template" : {…}

}

}

Links

"links" : [

{

"href": “https://foo.com/api/organizations/",

"rel": "organizations"

},

{

"href": “https://foo.com/api/customers/",

"rel": "customers"

},

],

Items

"items": [

{

"href": “https://foo.com/api/organizations/1/",

"data": [

{

"name": “organization_id”,

"value": “my_org”

}

],

"links": [

{

“href": “https://foo.com/api/organizations/1/customers“,

"rel": "customers"

},

]

}

]

Queries

"queries" : [

{"rel" : "search",

"href" : “https://foo.com/api/customers/search”,

"data" : [

{"name" : “last_name", "value" : ""}

]

}

],

Template

"template" : {

"data" : [

{"name" : “fist_name”, "value" : "", "prompt" : “First name”},

{"name" : “last_name”, "value" : "", "prompt" : “Last name"},

]

}

The Agenda

❖ REST overview

❖ Hypermedia

❖ Affordances

❖ Demo

Who’s using this stuff?

Who has written or consumed a REST API?

Questions?

❖ API Craft Google group/mailing list

❖ RESTful Web APIs (Richardson/Amundsen)

❖ Roy Fielding’s thesis/blog

❖ Hypermedia formats (HAL, Siren, Hydra, CJ, JSON-LD,

UBER, etc.)

❖ API Craft conference in Detroit (http://apicraft.org/)