Vendor MIME types (for API versioning)

Question

I have read many of the Stack Overflow (and other) posts on versioning RESTful services. It's a bit overwhelming, to be honest.

I've decided to use an Accept: header for our (marginally-) RESTful service so clients can request specific versions of a resource. What I'm not clear on is what to specify in the Accept header.

The example I have often seen is this:

Accept: application/vnd.mycompany.myapp.customer-v2+json

My questions are:

1. Am I correct that all vnd types must be registered? (http://www.iana.org/cgi-bin/mediatypes.pl)

2. Is the version and type (i.e. -v2+json) part of the type and so each version and type would need to be registered?

3. Is there any reason to use vnd instead of an "x-" subtype that does not need to be registered? For example:

   Accept: application/x-mycompany.myapp-v2+json
   

   The existing API is internal only, but in the future it will be exposed to customers.

4. Not sure this makes sense, but is it possible to use an existing type but add a version? (The current API returns "application/json")

   Accept: application/json-v2
   

5. What are acceptable formats for appending a version and type (e.g. -v2+json).

6. What if a client asks for a non-supported version? Is the correct response a 406? Can the client request any version? Or more generally, what if the client provides no Accept header or Accept: */*?

Any additional suggestions welcome. The goal, of course, is to allow changes to what the service returns for a given resource, but not break existing clients.

Here's a short list of resources I've looked at recently:

• Best practices for API versioning?
• How to version REST URIs
• REST api versioning (only version the representation, not the resource itself)
• http://www.lexicalscope.com/blog/2012/03/12/how-are-rest-apis-versioned/
• http://www.subbu.org/blog/2008/05/avoid-versioning-please
• http://www.informit.com/articles/article.aspx?p=1566460
• http://en.wikipedia.org/wiki/Internet_media_type#Prefix_vnd
• http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.1

Answer 1

As I have decided to follow the jsonapi.org standard, I decided to do just what your example shows.

Regarding your questions:

1. Your MIME type should be registered
2. I believe that each version and type should be registered, as they are unique types
3. x- prefix has been deprecated as noted in a comment
4. application/json-v2 would not be valid
5. You could return 415 Unsupported Media Type or simply 400 Bad Request