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

Bill Moseley moseley at hank.org
Tue Oct 1 14:12:46 CDT 2013

On Tue, Oct 1, 2013 at 8:17 AM, Matt Warden <mwarden at gmail.com> wrote:

> >> 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
> I don't really understand this distinction. I don't understand the use
> case where I would want to operate on v2 endpoints except in a couple
> cases where I want to use the v1 endpoint. And my brain starts to warp
> when I think about how you might move attributes from one endpoint in
> v1 into its own endpoint in v2. This just seems like an unnecessary
> complexity with no driving use case. That said, if internally you know
> that v1 and v2 of a given endpoint are exactly the same, you could
> route appropriately.
> In my opinion, you should establish unique namespaces for API versions
> and it should be wholesale.

Are you saying you might as well have  https://v1.api.example.com/... and
then later https://v2.example.com/ ?

I think the use case for versioning individual endpoints is reasonable.

Say you have mobile app that shows a list of widgets an the use can then
click on a widget in the list and show an individual widget.

Later, the service is expanded to return a new type or style of widget that
the existing clients cannot process.

So, old clients would use:

GET /v1/account/12434/widget  -- return list of widgets but excluding the
new type.

Then the service expands and provides

GET /v2/account/12434/widget  -- return list including the new widget type.

Then support both end points at the same time -- and thus support old and
newer clients at the same time.

May not even need to add a new "v2" method for fetching an individual

GET /v1/account/12434/widget/12948

Because older clients (using v1 to get the list) would never know URLs for
the new widgets.

The above may not be a great example because it might be a better design to
use a query parameter to specify which types of widget to return when
asking for the list/collection of widgets.

And in some ways I think v1 and v2 are different representations of a
collections of widgets, so that's why I like the idea of the version in the
Accept: header as being the right place instead of in the URL.   But...

Here is a pragmatic, non-religious video on how to design REST APIs:
> http://apigee.com/about/api-best-practices/api-design-third-edition

yes, there's is the pragmatic approach.   That's kind of the way we are

> >> What about adding .json?  I'm less excited about that.  This seems odd:
> >>
> >> GET https://example.com/v2/account/48483/thing/1432.json
> This is up to you. It is not necessary and is redundant with the mime
> type header.

The reason is really to make it clear, or really easy, for developers and
for debugging.   Makes looking at request logs very clear what's happening.
  Just feels a bit un-pure from a pure-REST approach...

Bill Moseley
moseley at hank.org

More information about the thelist mailing list