[thelist] Versioning URLs: Good plan or bad idea?
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
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
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:
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...
moseley at hank.org
More information about the thelist