Please, please don't help to persist the convention of putting the API version number in the URL. There are far better ways of doing it.
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...
Where does the madness end? Do you treat everything as though it were GET and stick the real method (and every other request header) in a query parameter? I think it's ok to assume a basic level of understanding of one of the best documented specs in computing.
A public API is about 99% of what we (Crocodoc) offer. While designing the latest version of our API, I always erred on the side of staying true to REST principles. Fortunately there were others on our team that erred on the other side. The result is a happy medium that certainly veers from the canonical definition of REST but is arguably easier for Joe Developer to play with. Guess what...we still receive an incredible amount of support requests from developers getting stuck.
It's tempting (and fun) to build APIs "the right way" and use little tricks like putting versioning in the media type. However, that's pretty often at odds with product/user experience/business considerations. Why offer a product that only 10% or 20% of your customers are savvy enough to use?
So you are willing to do the work of those other devs for them, and cripple your own API in the process?
For a simple developer, output format is just another parameter and it shouldn't be hidden in HTTP stack.
At least in python, making requests becomes quite a few more lines of code if you want to add headers. There's usually a short-hand command if you just want to get full data from an url and a "create-an-object, then set these parameters, then this, then open a connection then read what's there".
Mandatory headers are just a way to make life of a regular developer painful.
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,/;q=0.8
This says "we would prefer one of these formats, but we'll take whatever you got".
Now I navigate off the page to a different site, and press the back button. Instead of the HTML page, I get the cached JSON response. Now if I change the ajax call to "example.com/objects/1.json" instead, that keeps the URLs separate and the browser won't cache the wrong response. Is there a better way to solve this?
[1]https://developer.mozilla.org/en/HTTP/Content_negotiation
Think of all the different "Accept" headers that clients can send you, each one of these will get an entry in your cache. And now add other headers that should also be in "Vary" like "Cookies", "Accept-Language", etc. and your cache will be virtually useless.
Also, I might be nitpicking here, but I think the difference between a URL and a URI is that the URL explicitly defines the media type.
If that's the case, then the advice would be to use URIs pointing to resources in combination with `Accept` headers.
No, no. An URL is an URI. And the URL doesn't define any media-type, those are hacks created frameworks; there's no such thing in the spec.