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:

  1.  Get a menu to see the list of beer types
  2. Choose a type of beer to see what beers are available for that type
  3. Pick a beer and add it to your order
  4. Finalize the order by paying
  5. 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