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.
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.
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
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?
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.
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.
See also: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hyperte...