I'm not convinced that versioning media-types is the best way. I agree it is a more correct way as opposed to basically abusing REST, but I think overall putting the version in the URL is better.

From the linked answer:

> * you break permalinks

> * The url changes will spread like a disease through your interface. What do you do with representations that have not changed but point to the representation that has? If you change the url, you break old clients. If you leave the url, your new clients may not work.

Putting the version somewhere else in the request doesn't fix this. If you drop support for an old API version it is going to break stuff. It is easier to spot the issue if you return a 404 rather than a 500 or 400 error, or even correct data that breaks the app consuming the API as it is expecting something else.

> * Versioning media types is a much more flexible solution.

The main issue I have with this is I have had the "pleasure" of working with pretty stupid people implementing clients on my API. They easily get POST and GET requests mixed up, HTTP and HTTPS, whether or not the request should be authenticated. I don't want to add something else to confuse them even more...

Also don't put the format in the URL, that's what Accepts is for.

Beware that proxies sometimes strip the accept header. I know of at least one European ISP that does this for its 3gs users.