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

Renoir B. renoirb at gmail.com
Sun Sep 29 13:24:46 CDT 2013


Hello

I am not an implementation expert but a read a few books on the theory and
got to a better understanding of theory behind Hypermedia/REST.

Please do not take my word on it, but have a look at the references.

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.

2.  Use appropriate headers: e.g. Accept, Content-Type and also use it for
authentication

3.  To quote TimBL:  'Cool URI doesn't change'

It also apply to Hypermedia services.

The rest, have a look at [1] where Daviz Z. Shows common mistakes and [2]
where Steve K. gives a great introduction to the hypermedia.

Lastly [0] is a great mailing list regarding REST understanding.

  [0]: http://groups.yahoo.com/neo/groups/rest-discuss/info
  [1]: http://m.youtube.com/watch?v=NEWTPFzt2-E&feature=plpp
  [2]: http://m.youtube.com/watch?v=g4sqydY3hHU&feature=plpp

Regards,

Renoir Boulanger

http://w3.org/People/#renoirbhttps://renoirboulanger.com/  ✪  @renoirb
~
On Sep 25, 2013 9:56 PM, "Bill Moseley" <moseley at hank.org> wrote:

> 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.
>
> http://www.lexicalscope.com/blog/2012/03/12/how-are-rest-apis-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.
>
> https://example.com/v2/account/48483/thing
>
>
> or even include the representation:
>
> https://example.com/v2/account/48483/thing.json
>
>
> 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
> structure)
>
> 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
>
>
> Thanks,
>
> --
> Bill Moseley
> moseley at hank.org
> --
>
> * * Please support the community that supports you.  * *
> http://evolt.org/help_support_evolt/
>
> For unsubscribe and other options, including the Tip Harvester
> and archives of thelist go to: http://lists.evolt.org
> Workers of the Web, evolt !
>


More information about the thelist mailing list