Let's face it, the term "REST" has become too popular for its own good. Like so many other hyper-successful buzzwords, REST means very different things to different developers. If you think that REST loosely translates to "JSON over HTTP", then it's time for a hypermedia intervention. In this talk, you'll learn about the core tenants of RESTful design, where the major frameworks go astray, and why it matters. We'll also discuss some of the exciting things going on in the hypermedia community, and how you can take advantage of them to build more awesome clients and servers.

1. Chris Marinos presents:
Hypermedia APIs:
The Rest of REST

2. The Agenda
❖ REST overview
❖ Hypermedia
❖ Affordances
❖ Demo

5. Who has written or consumed a REST API?

6. What is REST?

7. –Chris Marinos
REST APIs are where you, like, follow HTTP and stuff

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

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

10. REST is the architectural style of the internet

11. REST Constraints
❖ Client-Server
❖ Stateless
❖ Cache
❖ Uniform Interface
❖ Layered System
❖ Code-On-Demand (optional)

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

13. No HTTP?

14. –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.”

15. The Agenda
❖ REST overview
❖ Hypermedia
❖ Affordances
❖ Demo

16. HATEOAS
Hypertext as the Engine of Application State
(also a horrible acronym)

17. So what is hypermedia?

18. Richardson Maturity Model
Level 0: Pox
Level 1: Resources
Level 2: HTTP Verbs
Level 3: Hypermedia Controls
REST

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

20. 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’
}

21. 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’
}

22. 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’
}

23. The Agenda
❖ REST overview
❖ Hypermedia
❖ Affordances
❖ Demo

24. “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

25. Affordances

26. State transitions over URL structure

27. Hypermedia Benefits
• API discoverability and documentation
• Reuse of state transition logic across clients
• Ease of client development
• More flexibility for servers to evolve

28. Hypermedia Formats
HTML
XHTML
Collection+JSON
Siren
HAL
JSON-LD
NOT JSON or XML

29. Collection+JSON
{
"collection" :
{
"version" : “1.0",
"href" : “https://foo.com/api/“,
"links" : […],
"items" : […],
"queries" : […],
"template" : {…}
}
}

30. Links
"links" : [
{
"href": “https://foo.com/api/organizations/",
"rel": "organizations"
},
{
"href": “https://foo.com/api/customers/",
"rel": "customers"
},
],

31. 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"
},
]
}
]

32. Queries
"queries" : [
{"rel" : "search",
"href" : “https://foo.com/api/customers/search”,
"data" : [
{"name" : “last_name", "value" : ""}
]
}
],

33. Template
"template" : {
"data" : [
{"name" : “fist_name”, "value" : "", "prompt" : “First name”},
{"name" : “last_name”, "value" : "", "prompt" : “Last name"},
]
}

34. The Agenda
❖ REST overview
❖ Hypermedia
❖ Affordances
❖ Demo

35. Who’s using this stuff?

36. Who has written or consumed a REST API?

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