REST implies Content Negotiation by Mark Seemann
If you're building REST APIs, you will eventually have to deal with Content Negotiation.
Some REST services support both JSON and XML, in which case it's evident that Content Negotiation is required. These days, though, more and more services forego XML, and serve only JSON. Does that mean that Content Negotiation is no longer relevant?
If you're building level 3 REST APIs this isn't true. You'll still need Content Negotiation in order to be able to evolve your service without breaking existing clients.
In a level 3 API, the distinguishing feature is that the service exposes Hypermedia Controls. In practice, it means that representations also contain links, like in this example:
{
"users": [
{
"displayName": "Jane Doe",
"links": [
{ "rel": "user", "href": "/users/1234" },
{ "rel": "friends", "href": "/users/1234/friends" }
]
},
{
"displayName": "John Doe",
"links": [
{ "rel": "user", "href": "/users/5678" },
{ "rel": "friends", "href": "/users/5678/friends" }
]
}
]
}
This representation gives you a list of users. Notice that each user has an array of links. One type of link, identified by the relationship type "user", will take you to the user resource. Another link, identified by the relationship type "friends", will take you to that particular user's friends: another array of users.
When you follow the "user" link for the first user, you'll get this representation:
{
"displayName": "Jane Doe",
"address": {
"street": "Any Boulevard 42",
"zip": "12345 Anywhere"
}
}
This user representation is richer, because you also get the user's address. (In a real API, this representation should also have links, but I omitted them here in order to make the example more concise.)
Breaking changes #
As long as you have no breaking changes, all is good. Things change, though, and now you discover that a user can have more than one address:
{
"displayName": "Jane Doe",
"addresses": [
{
"street": "Any Boulevard 42",
"zip": "12345 Anywhere"
},
{
"street": "Some Avenue 1337",
"zip": "67890 Nowhere"
}
]
}
This is a breaking change. If the service returns this representation to a client that expects only a single "address" property, that client will break.
How can you introduce this new version of a user representation without breaking old clients? You'll need to keep both the old and the new version around, and return the old version to the old clients, and the new version to new clients.
Versioning attempt: in the URL #
There are various suggested ways to version REST APIs. Some people suggest including the version in the URL, so that you'd be able to access the new, breaking representation at "/users/v2/1234", while the original representation is still available at "/users/1234". There are several problems with this suggestion; the worst is that it doesn't work well with Hypermedia Controls (links, if you recall).
Consider the list of users in the first example, above. Each user has some links, and one of the links is a "user" link, which will take the client to the original representation. This can never change: if you change the "user" links to point to the new representation, you will break old clients. You also can't remove the "user" links, for the same reason.
The only way out of this conundrum is to add another link for the new clients:
{
"users": [
{
"displayName": "Jane Doe",
"links": [
{ "rel": "user", "href": "/users/1234" },
{ "rel": "userV2", "href": "/users/v2/1234" },
{ "rel": "friends", "href": "/users/1234/friends" }
]
},
{
"displayName": "John Doe",
"links": [
{ "rel": "user", "href": "/users/5678" },
{ "rel": "userV2", "href": "/users/v2/5678" },
{ "rel": "friends", "href": "/users/5678/friends" }
]
}
]
}
In this way, old clients can still follow "user" links, and updated clients can follow "userV2" links.
It may work, but isn't nice. Every time you introduce a new version, you'll have to add new links in all the places where the old link appears. Imagine the 'link bloat' when you have more than two versions of a resource:
{
"users": [
{
"displayName": "Jane Doe",
"links": [
{ "rel": "user", "href": "/users/1234" },
{ "rel": "userV2", "href": "/users/v2/1234" },
{ "rel": "userV3", "href": "/users/v3/1234" },
{ "rel": "userV4", "href": "/users/v4/1234" },
{ "rel": "userV5", "href": "/users/v5/1234" },
{ "rel": "friends", "href": "/users/1234/friends" },
{ "rel": "friendsV2", "href": "/users/1234/V2/friends" }
]
},
{
"displayName": "John Doe",
"links": [
{ "rel": "user", "href": "/users/5678" },
{ "rel": "userV2", "href": "/users/v2/5678" },
{ "rel": "userV3", "href": "/users/v3/5678" },
{ "rel": "userV4", "href": "/users/v4/5678" },
{ "rel": "userV5", "href": "/users/v5/5678" },
{ "rel": "friends", "href": "/users/5678/friends" },
{ "rel": "friendsV2", "href": "/users/5678/V2/friends" }
]
}
]
}
Remember: we're talking about Level 3 REST APIs here. Clients must follow the links provided; clients are not expected to assemble URLs from templates, as will often be the case in Level 1 and 2.
Versioning through Content Negotiation #
As is often the case, the root cause of the above problem is coupling. The attempted solution of putting the version in the URL couples the identity (the URL) of the resource to its representation. That was never the intent of REST.
Instead, you should use Content Negotiation to version representations. If clients don't request a specific version, the service should return the original representation.
New clients that understand the new representation can explicitly request it in the Accept header:
GET /users/1234 HTTP/1.1 Accept: application/vnd.ploeh.user+json; version=2
Jim Liddell has a more detailed description of this approach to versioning.
It enables you to keep the user list stable, without link bloat. It'll simply remain as it was. This means less work for you as API developer, and fewer bytes over the wire.
Disadvantages #
The most common criticisms against using Content Negotiation for versioning is that it makes the API less approachable. The argument goes that with version information in the URL, you can still test and explore the API using your browser. Once you add the requirement that HTTP headers should be used, you can no longer test and explore the API with your browser.
Unless the API in question is an anonymously accessible, read-only API, I think that this argument misses the mark.
Both Level 2 and 3 REST APIs utilise HTTP verbs. Unless the API is a read-only API, a client must use POST, PUT, and DELETE as well as GET. This is not possible from a browser.
Today, many APIs are secured with modern authentication and authorisation formats like OAuth, where the client has to provide a security token in the Authorization header. This is not possible from a browser.
Most APIs will already be impossible to test from the browser; it's irrelevant that versioning via the Accept header also prevents you from using the browser to explore and test the API. Get friendly with curl or Fiddler instead.
Summary #
If you want to build a true REST API, you should seriously consider using Content Negotiation for versioning. In this way, you prevent link bloat, and effectively decouple versioning from the identity of each resource.
If you've said REST, you must also say Content Negotiation. Any technology you use to build or consume REST services must be able to play that game.
Comments
For that example, it's only a breaking change because you also removed the old "address" property. It might have been easier to leave that in and populate it with the first address from the collection. Older clients could continue to use that, and newer ones could use the new "addresses" field. Obviously at some point you will need to deal with versioning, but it can be better to avoid it until absolutely necessary.
I've been catching up on REST, and discovered the 5 levels of media type just a few minutes before reading your post. This keeps it approachable, you can still use your browser to explore, and the higher levels progressively enhance the API for smarter clients.
An example can be found here where Ali Kheyrollahi exposes Greg Young's CQRS sample though a REST inferface.
Graham, thank you for writing. You are completely right: if it's possible to evolve the API without introducing a new version, that's always preferable. Your suggestion for doing that with my particular example demonstrates how it could be done.
As you also correctly point out, sooner or later, one will have to deal with a truly breaking change. My purpose of writing this article was to explain how the need to do that implies that content negotiation is required. This is the reason I made up an example of a breaking change; unfortunately, that example didn't convince you that versioning was necessary ;)
I think I would consider going one step further, and mandate a version in the Accept header right from the beginning.
i.e.,
Accept: application/jsonwould return a 406 Not Acceptable HTTP response. You have to useAccept: application/vnd.ploeh.user+json; version=1Forces clients to be upgrade friendly to begin with, and easier to retire old versions when they are not being called any more.
It strikes me though, that having to know these MIME types for versioning is a bit like needing to know the right incantation to open the magic door. We don't want clients hard-coding the URL to a particular API call as part of HATEOAS, but still need to know the magic MIME type to get an appropriate version of the data.
Evan, thank you for writing. As I also wrote in a comment to Jim Liddel's article, I would consider the context before making any hard rules. If you control both API and all clients, requiring specific Accept headers may make managing the entire ecosystem a little easier.
On the other hand, if you make an API available to arbitrary clients, you should follow Postel's law in order to make it easy for client developers to use your API.
Ultimately, even if you can somehow solve the problem of not having to know specific MIME types, you'll still need to know how to interpret the representations served by the API. For example, as a client developer, you still need to know that a user representation will have
displayNameandaddressproperties. As far as I can see, you can push that problem around, but if it can be solved, I've yet to learn how.Mark, I've been doing some preliminary research on API versioning for a personal project and I like this approach. Thanks for the post and accompanying links!
I read a few of Jim Liddel's posts and can see that Nancy has this sort of content negotiation baked in. Being more familiar with Web Api, I've been looking for an existing way of doing this using that framework instead. Web Api's support for attribute routing seems promising, but as of yet, I haven't seen any examples of this in action using Web Api 2. The flexibility and simplicity of Nancy is really attractive, and I may end up going that route anyway, but I'm hesitant to pick a framework based solely on something like this. Have you come across anything similar for Web API 2?
Ben, thank you for writing. Web API has supported Content Negotiation since back when it was still a WCF Web API CTP. Out of the box it supports XML and JSON, but you can also make it support Content Negotiation-based versioning as described in this article.