In a recent tips for versioning post and on the RESTful API Design webinar, I described some best practices for versioning your APIs - move the v as far left in the URL as possible; place it at the highest scope (e.g. /v1/resources); and use a simple ordinal number, no dot notation.
I wanted to follow up with a little more on versioning, inspired by some great discussion on API craft (keep it coming!).
As I mentioned on the video, there is a strong school of thought about putting format and version in the header.
I think that sometimes people are forced to put the version in the header because they have multiple inter-dependent APIs. That is often a symptom of a bigger problem, namely, they are usually exposing their internal mess
instead of creating a usable API facade on top.
That's very different than saying putting the version in the header is a symptom of a problematic API design. It's not!
In fact, using headers is more correct for many reasons: it leverages existing HTTP standards, it's intellectually consistent with Fielding's vision, it solves some hard real-world problems related to inter-dependent APIs, and more.
However, I think the reason most of the popular APIs do not use it is because it's less fun to hack in a browser.
Simple rules I follow:
If it changes the logic I write to handle the response, put it in the URL so I can see it easily.
If it doesn't change the logic for each response, like OAuth stuff, put it in the header.
These for example, all represent the same resource:
The code I would write to handle the responses would be very different.
There's no question the header is more correct and it is still a very strong API design.
Next in the series on RESTful API Design: pagination and partial response - how to return just what developers need.
Meanwhile, I'd love to hear more of your thoughts in the API Craft Google group.