hypermedia apis: the rest of rest
TRANSCRIPT
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/)