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

[Matt Warden]

On Sun, Sep 29, 2013 at 1:24 PM, Renoir B. <renoirb at gmail.com> wrote:
> 1.  I would prefer exposing a root endpoint as a proxy that navigates for
> you depending on the query parameters.
> Neat advantage of this is that if your database sxhema changes, you update
> the proxy and nothing else has to change.

That's great in theory, but how many API-consuming applications
actually operate like this? How many apps request the root and then
inspect the response to understand how to make its next move? I've
never seen anyone implement an API-consuming application like this,
except to make a religious point.


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

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

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

-- 
Matt Warden
http://mattwarden.com


This email proudly and graciously contributes to entropy.