hypermedia apis: the rest of rest
TRANSCRIPT
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 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
–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.”
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’
}
“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
Hypermedia Benefits
• API discoverability and documentation
• Reuse of state transition logic across clients
• Ease of client development
• More flexibility for servers to evolve
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"},
]
}
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/)