Best way to specify version in REST service calls

Question

Possible Duplicate:
How to version REST URIs

I'm currently writing a REST service and I would like to get some ideas on how my clients can specify the service version when making a request.

For example when I upgrade my REST server to version 2 I don't want calls to break for all clients that have implemented version 1 of my service.

I've seen others add the version in the url or specify the version in the header somewhere.

There may not be a "best" way to implement this but I would appreciate some thoughts on the subject( pro's and con's of each etc...)

Thanks

Answer 1

We do it via separate routes:

 http://my.service.com/v1/user/1

 http://my.service.com/v2/user/1

In the case of no change between versions, we just map the route to the controller that services the v1 version of the resource.

Yes, this does create multiple URL's for the same resource, and the wonky hardcore REST evanginlists will start crying, but this way makes it easy to manage for you and your users. I find users can't even use request headers to set things like content types nevermind an X-Path or something like that to handle versioning....

If you really want to avoid the duplicate resource issue, you couldpass in a get paramter like version:

 http://my.service.com/user/1?version=1

If no version, default to whatever. This is actually fully REST dogmatic, but I think it puts a lot onto your API users.

You could do some kind of user lookup table to route between version if you have a way to map user or api key to version, but this is pretty crazy overhead.

Answer 2

I would recommend versioning via the Accept/Content-Type header. The URIs shouldn't change across versions unless there is a large structural change to the resources themselves. Here is a great explanation: Best practices for API versioning?