Why You Should Consider Content Negotiation for REST APIs

With the steady trend away from XML and toward JSON in REST services, content negotiation has become seemingly less relevant. However, according to a post by Mark Seemann on the Ploeh Blog, content negotiation is still required in some REST APIs to avoid breaking the client.

First, content negotiation is the HTTP specification that allows the delivery of two versions of a resource representation at the same URI so the client can use the most appropriate one for its capabilities. With this in mind, it is important to remember that level 3 REST APIs expose hypermedia controls, so the representations also contain links.

With hypermedia allowing the returning of richer information, the delivery of, for example, two properties when the client is expecting one can initiate a break. There are suggestions to include the version in the URL, but that doesn’t always work well with hypermedia controls due to coupling, which goes against RESTful intentions.

Using content negotiation instead allows you to keep the user list stable while avoiding link bloat with less development work and smaller loads. Furthermore, since most APIs that aren’t read only cannot be properly tested from the browser using HTTP verbs, the common criticism that using HTTP headers stifles exploration of the API using the browser becomes less critical.

So to reduce development work and link bloat, and decouple versioning from the ID of each resource, consider using content negotiation for versioning of your next REST API project.

Original Article

REST implies Content Negotiation

Martin W Brennan Martin W Brennan is a co-founder of ViewPop, the social network that puts the creation of 3D photos and videos in the hands of anyone with a smartphone. For his day job, Martin is a copywriting consultant at We Write Words, learning about the world as he writes about it.