[thelist] Versioning URLs: Good plan or bad idea?

Bill Moseley moseley at hank.org
Wed Sep 25 20:55:50 CDT 2013

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.


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.


or even include the representation:


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

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


Bill Moseley
moseley at hank.org

More information about the thelist mailing list