rest At it's best
Hypermedia APIs With PHP
Brian Scaturro - @scaturro - github.com/brianium
THATS not REST!
Roy Fielding has this to say:
"What needs to be done to make the REST architectural style clear on the notion that hypertext is a constraint? In other words, 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. Is there some broken manual somewhere that needs to be fixed?"
The richardson Maturity Model
We have worked with HTTP for some time, but we have never really reached for the true "glory of REST."
The "Richardson Maturity Model" is a model created by Leonard Richardson that breaks REST maturity down into 3 levels (4 including 0).
LEVEL 0: The swamp of pox
POX = Plain Old XML
While XML is in the title, this method can work with any data format. At this level - HTTP is little more than a way to transport data.
No real attention to verbs or nouns.
XML-RPC , SOAP - these are just fancy ways of frolicking in the swamp of pox.
LEVEL 1: Resources
At this level we stop interacting with a single endpoint, and start to think about interacting with individual resources.
At this level we are at least distinguishing between different resources in our system. We gain some separation, and this sits a little better with those of us who think in terms of objects.
Level 2: Verbs
At this level we start to really leverage the HTTP protocol. We are still interacting with resources, but we are also identifying safe and unsafe operation through the use of verbs like GET, POST, PUT, and DELETE
This seems to be a pretty safe place for most people designing APIs, and it is one encouraged by many modern frameworks.
Level 3: Hypermedia controls
Haters going to hate on hateoas
Hypermedia As The Engine Of Application State
What is hypermedia?
It's media with links!
The engine of application state
Our linkable media drives application state forward. In a sense our APIs are self descriptive and each response should show where our application state is, and what we can do to manipulate that state.
WHAT DOES IT MEAN TO 'DO' SOMETHING?
AFFORDANCES
Affordances are what we can do. If we look at a noun-centric API design we may have the following endpoints:
GET /menu - returns a menu
POST /menu/beertype - Adds a type of beer to the menu
How do we know we can add beer types to a menu without some level of documentation? It would be nice if our API told us our affordances directly.
Including affordances in the response
GET /menu - returns a menu
{
"_links": {
"self": {"href": "/be.er/menu/1"},
"http://be.er/rels/beertype": {"href": "/be.er/menu/1/beertype"}
},
"id": "54cde43dcd",
"name": "Specialty Beers"
}
The consistency of http
We have shifted our affordances - the "what we can do" - aspect of our API into the response. No need to create custom verbs...
Imagine the conflicts if we used requests like:
BEERTYPE /menu/1
THERE WOULD BE CHAOS!!!
HTTP has a consistent interface that we know we can rely on. We have an affordance - that is a thing we can do - in the beertype link, and we know it is confined to POST (create), PUT (update), GET (read), and DELETE (delete) operations.
Resources
If affordances are our verbs, we still have our nouns. The "what's" of the operation. If we think of an algorithm for ordering beer through an API:
- Get a menu to see the list of beer types
- Choose a type of beer to see what beers are available for that type
- Pick a beer and add it to your order
- Finalize the order by paying
- Get a receipt
What are our affordances, and what are our resources?
affordances: get a menu, get a list of beer types, get a list of beers, add a beer to your order, finalize the order, pay with your credit card, and get a receipt.
resources: menu, type, beer, order, receipt
demonstration
BEER API BUILT WITH SILEX:
rest at its best
By Brian Scaturro
rest at its best
- 1,173