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 (http://www.w3.org/wiki/LinkHeader) is potentially a good way of achieving this, though exactly how this works in practice is still being considered.