[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
widget:

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
leaning.



>
>
> >> 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