Versioning a RESTful API with both XML and JSON Content-Type

Question

According to this excellent presentation on designing RESTful interfaces, the preferred way to implement versioning is to utilize the Accept-header, using something like:

Answer 1

You can implement versioning either by adding a version in the content type:

application/vnd.acme.user-v1+xml

Or you can also use a qualifier in your Accept header, that way you don’t touch your content type:

application/vnd.acme.user+xml;v=1

You can split your content type application/vnd.acme.user+xml in two parts: the first one (application/vnd.acme.user) describes the media type, and the second one (xml) the format of the response. That means you can use another format like json: application/vnd.acme.user+json.

In the HATEOAS world, XML is better than JSON for readability and semantic purposes, if you want to use JSON, you could be interested by this specification: https://github.com/kevinswiber/siren.

Answer 2

The cleanest way I know is by using profiles. There is an IETF RFC for that (RFC 6381).

Using the accept header, indicate what type of response you expect. You can still use qualifiers as well. You can request compliance with one or more comma-separated profiles, but you must use quotes if you specify more than one profile.

Accept: application/json; profiles="http://profiles.acme.com/user/v/1"

Using the content-type header, the server can respond alike:

Content-Type: application/json; profiles="http://profiles.acme.com/user/v/1"