I've been trying to get a lot of input and opinions on API versioning, and wondering if anyone has a compelling reason to use or not use a version in the URL. There's quite a few discussions about how to version an API -- and the options are mostly either using a custom MIME type and version in the Accept: header vs. adding a version in the URL. Here's a pretty good summary of discussions and how some APIs are versioned. http://www.lexicalscope.com/blog/2012/03/12/how-are-rest-apis-versioned/ My take on it is that using Accept: and a custom MIME type is the "correct" approach for a RESTful API. But, from a practical point of view having everything expressed in the URL might be the way to go. Sure would make debugging and testing nicer w/o having to know what Accept: header was used. https://example.com/v2/account/48483/thing or even include the representation: https://example.com/v2/account/48483/thing.json And to be clear, that version is not the overall API version, but the version of that specific endpoint. So, there might be in the same API PUT https://example.com/v1/account/48483/thing/1432 GET https://example.com/v1/account/48483/thing/1432 as well as this that returns a newer representation (perhaps different json structure) GET https://example.com/v2/account/48483/thing/1432 See any real big problems with this approach? What about adding .json? I'm less excited about that. This seems odd: GET https://example.com/v2/account/48483/thing/1432.json And finally, any thoughts on using semantic versioning? GET https://example.com/v2.5.2/account/48483/thing/1432 Thanks, -- Bill Moseley moseley at hank.org