1

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

Community
  • 1
  • 1
RayLoveless
  • 19,880
  • 21
  • 76
  • 94
  • Have you read this? Good overview of this very subject, along with some useful links - http://www.infoq.com/news/2010/03/rest-versioning-strategies. – dash Oct 11 '12 at 20:41
  • This sounds like a bad idea, you should not modify already existing functionality like this (hence using versions). When creating a public service/api/whatever you may call it - you have one chance to get it right! – Anders Oct 11 '12 at 20:41

2 Answers2

4

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.

Ray
  • 40,256
  • 21
  • 101
  • 138
  • This solution is good because it allows for different URL patterns in different versions. If you were to use a URL parameter like `version=1` instead, your paths would need to be the same across API versions. – JasonWyatt Oct 11 '12 at 20:40
  • 1
    @JasonWyatt see my edits about the url parameter. Hopefully your resource locations don't change significantly across software versions... that one of the most important things to avoid when creating user API's. I know they do, and I know the v1, v2 thing is a change, but the rest of the resource path hopefully stay's pretty constant. I think users get changing a v1 to v2 when they're ready to use your new version. – Ray Oct 11 '12 at 20:48
  • @JasonWyatt also, after a certain amount of time to let old api's depricate you can just route the old v1's over to v2. – Ray Oct 11 '12 at 20:49
  • For now I think this is the most "practical" way of doing it. I'm not totally sold on versioning the Accept type. – RayLoveless Oct 22 '12 at 16:07
0

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?

Community
  • 1
  • 1
johnlcox
  • 520
  • 6
  • 12
  • As the client specifies the accept header to tell the server what format he prefers the response to be in I think this makes sense. But what if the specific service call has no response or simply response of 200 with "successfully updated"? ..It would makes sense here to do the version in the url. Rather than doing the versioning in both places it makes sense to me to keep it simple and version the url. – RayLoveless Oct 22 '12 at 16:26