Ask HN: Version numbers in a REST API

Re:Ask HN: Version numbers in a REST API by defeated on Saturday July 17, 2010 @11:31AM (#1523928)

Actually, I think best practice is to not put the version number in the URI at all. Instead versioning should be handled via content negotiation. That is to say, a client specifies the type of resource they want back via the Accepts: header, and that resource is versioned. So A request would look something like:

GET /client

Accepts: application/vnd.clientlist.v1+json

And they would get back the version 1 client list response. If they want v2, etc, they can specify a different content type (clientlist.v2+json, etc). Also note, that putting verbs in your URIs is counterintuitive. The verb for a REST operation is the HTTP method (GET, POST, PUT, DELETE). The URI should simply represent the resource being retrieved. An argument can be made that the client list is the resource, but in reality listing things from a REST API is a first class concept and shouldn't need separate URIs. It's simply a request for a specific resource type without qualifying it by asking for a single instance of that resource. So, GET /client would return all clients (can add query parameters for pagination, etc), GET /client/834 would return a single client resource.

[ Parent | on HN ]

Re:Ask HN: Version numbers in a REST API by psadauskas on Saturday July 17, 2010 @12:21PM (#1524045)

Can I have a few more upvotes please? This is the only way to do it. There's currently two root posts above this one advocating the incorrect way, with versions in the URL.

By doing it this way, you don't break links when you want to bump versions. Or if you have a single resource with an incompatibility, you can just upgrade the version of it, and leave all the others the same, without having to change anything, or your clients having to change theirs, either.

I wrote a blog post about this awhile back, please see point #4: http://blog.theamazingrando.com/your-web-service-might-not-b... (apologies for the formatting, I just imported it to Posterous, and it seems their styles aren't quite right)

Also, a former coworker of mine wrote a series of posts about this topic as well: http://barelyenough.org/blog/2008/05/versioning-rest-web-ser... http://barelyenough.org/blog/2008/05/versioning-rest-web-ser... http://barelyenough.org/blog/2008/05/resthttp-service-versio...

[ Parent | on HN ]

Re:Ask HN: Version numbers in a REST API by killedbydeath on Saturday July 17, 2010 @02:24PM (#1524327)

Isn't the point of bumping version to signal incompatible API changes? In that case breaking links is probably a better solution.

[ Parent | on HN ]

Re:Ask HN: Version numbers in a REST API by bl4k on Saturday July 17, 2010 @03:28PM (#1524469)

Answer needs more love. The capabilities of the client are part of content negotiation. The version that the client supports is thus also part of content negotiation, just like content format, language, character set, compression method, etc. are

Please do not place the version number in the URL, it is a horrible practice

[ Parent | on HN ]

Re:Ask HN: Version numbers in a REST API by reynolds on Saturday July 17, 2010 @01:21PM (#1524199)

Unless I'm mistaken, this basically tells me that I should put the same code for v1+json and v2+json in the same controller method, rather than actually dispatching to separate controllers. I'm not sure how it's done in Rails, but /v1/ and /v2/ are dispatched separately since they are different namespaces.

Also, how do you separate users accessing your API if not with X-* HTTP headers with an API key? (I'm referencing that link you posted). Would you not consider Gowalla (and hundreds of others who use X-* API key headers) as being RESTful?

[ Parent | on HN ]

Re:Ask HN: Version numbers in a REST API by danielvlopes on Saturday July 17, 2010 @07:30PM (#1524862)

In rails3 we could use constraints to limit requests to header x to be routed to controller x and vice versa for controller y. I dont tested it yet to be sure but I think its totally possible.

[ Parent | on HN ]