Hypermedia types and connection negotiation

September 25, 2012 Uncategorized 3 comments ,

I was fortunate enough to be able to travel to RESTFest in Greenville SC over the past week to spend time mixing with people who are highly influential in the world of REST and Hypermedia. Many interesting things where discussed there and it got me thinking about connection negotiation a little more (one of many many things I have taken away from the conference – subjects for later articles!)

Before attending the conference I had always advocated taking an existing hypermedia type (for the examples here I will use application/hal+json) and trying to represent a resource using that. More often than not, I would require some affordances that are not defined in the spec – so extending it and creating my own vender specific mime type (which defines what base type it extends) made a lot of sense to me.

Now that various media types are become ubiquitous amongst API designers (Hal and collection+json amongst others), it’s made me see the advantage of sticking to the base type whilst negotiating with the server on what content you receive. The reason? Because other clients that understand these hypermedia types are staring to emerge – much like the web browsers in which we browse the text/html hypermedia type today.

Like HTML, hypermedia types are created with the understanding that if an element exists that the client is not able to assign meaning to (an affordance that is not part of the spec, or not implemented by the client), then it can simply ignore it as if it was never there. This is quite powerful – it allows you to define optional extensions to a hypermedia type whilst maintaining compatibility with clients and intermediaries which already understand your base type.

Collection+json supports this idea quite well, and the author (Mike Amundsen) accepts additional patches to define extensions as part of the specification – extensions that one day could form part of a revised version of the specification for everyone to use, but exist as extensions that can be understood by any third party client that support them.

It is now my opinion that the creation of custom mime types (without registering them with IANA) actually harm the interoperability of the web – and close down a hypermedia API to clients which have specifically been created for your own hypermedia type.

Perhaps a missing piece of the puzzle right now is a way of being able to declare which extensions your document is actually making use of (if this is even needed once the extensions become part of the specification). Using a Link header ( is potentially a good way of achieving this, though exactly how this works in practice is still being considered.

Comments encouraged!

Writing RESTful clients

July 18, 2012 Uncategorized 3 comments , ,

There’s plenty of articles out there on how to build the perfect REST API, so I am not going to go into that. This article is all about what to think about when you’re building the perfect client for a REST API. What you’re being served is clearly important – but how you use that information is 50% of the problem – and it needs to be done correctly.

API designers can spend a lot of time ensuring that their responses to you are perfectly well formed and self describing – but unless you pay attention to what it is that those messages are telling you, all that information is simply being thrown away.

Connection Negotiation

The very first thing your HTTP client will send to the server is the Request headers. Within that request, more often than not, you will send the Accept header and a list of media types that your client can support – and the order of preference within which you would like to see them. Chrome 20.0.1132.47 sends the following Accept header.


Obviously this is a web browser, so it’s preference is going to be for text/html or application/xhtml+xml. Failing that, we can also take application/xml. If the server still can’t handle the request – then we’ll take anything at all (*/*).

The web server will make a decision based on what your client has asked for. From that point on one of 3 things can happen. 1) You get back one of the media formats that you asked for. 2) You receive a 406 response (Not Acceptable). 3) You get back something you didn’t ask for at all (this is allowed as per RFC2616 – the server SHOULD only respond with a 406).

This means that unless you’re explicitly checking what the response is after the request comes back – you could find yourself only assuming that the server is behaving as you think it is.

The Accept header becomes very useful when you separate out a normal response from an error response. In the situation where a server error is causing a problem, you are likely to receive a 5xx response code from the server with little or no meaningful body (text/plain). Where an application error has occured you should also receive a 5xx (or a 4xx) code from the server – however having declared you are able to handle a more specific media type (application/vnd.error+xml for example), you are able to present more information to the user than you would otherwise be able to.

Take the situation where you are consuming an API which serves up application/hal+xml and text/plain (hal for the resource representation, and a plain text for an error). The server is free to be able to add support for representing errors in application/vnd.error+xml without affecting any existing client – as long as the server continues to serve text/plain unless the new media type is deemed as acceptable to the client. Once the client is updated to add support for the new media type, it can take advantage of the additional information that can be provided.


A RESTful API will contain explicit directives that declare if and for how long the response body can be cached for. This information is contained across Cache-Control / Vary headers or Expires header. If the response to your request comes back from the server and declared itself as being able to be cached (only Cache-Control: no-store is excluded from user-agent caches) then you should store it locally and serve up the cached response as long as it’s valid.

There are of course already libraries you can use in your projects that will handle cacheing for you. If you usually use PHP for this stuff (I do), then I highly recommend you take a look at Guzzle to handle this for you.


Yeah i’m going to talk about it again. Hypertext as the engine of application state. Golden rule #1, never construct links in code (unless you’re following a URI Template) – follow them from the links given to you in the resource. This means that when these links change – you don’t have to worry about your app breaking. #2, use the defined link relations of the hypermedia type to navigate through the application (ie, HTML’s ‘rel’ attribute on the link tag). That’s about it. Don’t assume anything if it’s not defined by the media type rules and the representation you receive and you can’t go wrong.

REST and the Hypermedia Constraint

January 8, 2012 Uncategorized 1 comment , ,

The video of my talk at PHPNW ’11 has now been posted online at


Ryan Tomayako – How I explained REST to my wife

October 11, 2010 Uncategorized No comments ,

Having attended a talk by David Zuelke on Saturday at the PHPNW Conference 2010, he provided a link at the end of his talk to a blog post by Ryan Tomayoko, titled ‘How I explained REST to my wife’.

It’s a brilliantly simple explanation of something that I have struggled to vocalise for a few years!

Here it is in all it’s glory (don’t be scared by the size of the page – it’s mostly comments!).

Ryan Tomayoko – How I explained REST to my Wife