Future-proofing all aspects of RESTful web services [closed] - api

Question

As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 10 years ago.
We see REST web services as a way of "future-proofing" our business, among other things. I'm thinking through the tradeoffs of various ways of versioning our REST Web Services and I would like to find out what others have learned when it comes to versioning REST web services.
There are lots of good discussions on SO and other places about versioning web services, but most of them focus on whether to put the version number in the URL or the request header.
Versioning web services has multiple aspects to it. There is specifying the version in the web service call itself (URL or header). There is managing multiple versions of business logic in source code. There is building versioned web services. There are version control issues. And there is the matter of how to deprecate and drop obsolete versions.
Our partner who is writing our mobile clients wants to put the version in the URL so that is my approach (for now). In addition, the new versions of these web services may not be compatible with the old versions. For example there may be a different security implementation in different versions.
When it comes to versioned URLs two approaches are usually suggested - put the verion number in the URL or make it a parameter
context-root/service/rest/v0.1/restMethod/param1
context-root/service/rest/restMethod/param1?version=v0.1
The second method requires some controller logic to route the request to the right implementation, but that's not difficult. The choice between the two isn't difficult.
A third option is to put the version number in the context-root itself which means putting it in the .war filename prefix or in the deployment descriptor:
restarchive-v0.1/service/rest/restMethod/param1
This would mean deploying multiple archives for all versions currently supported.
I like having version numbers in filenames. It makes it easy to see what is deployed. The downside to this approach is that it requires a seperate build for each versioned archive, maybe with maven profiles.
Here's what the code for the first approach could look like. Each web method does it's own controller logic for all supported versions for that method. Business logic for each version can be handled a sensible way (i.e. put the version number in the package).
#ApplicationPath("/service/rest")
#Path("/{version}/")
public class RestService extends Application {
#GET
#Path("/user/{id}")
#Produces(MediaType.APPLICATION_JSON)
public User getUser(#PathParam("version") String version, #PathParam("id") int id) {
User user;
if (version.equals("v0.1")) {
// call v0.1 code to get the User
}
else if (version.equals("v0.2")) {
// call v0.2 code to get the User
}
else {
throw new WebApplicationException(Response.Status.NOT_FOUND);
}
return user;
}
}
My first implementation of this used multiple subclasses of javax.ws.rs.core.Application in different packages with the version number in the package. That should work, but the JBoss RESTeasy implementation doesn't allow multiple subclasses of Application in one .war. That apparently is a violation of the JAX-RS 1.1 specification, but it's a limitation you'll have to live with if you use JBoss or RESTeasy.
I'm inclined to use the first approach with an implementation similar to the one above. Since I'm trying to minimize problems in the future I would like to hear what others have learned through experience with the various aspects of version web services.
Is this a sound approach, or will it lead to problems that I haven't mentioned here?

Answer 1

This topic was brought up at JavaOne, and there is no right answer.
The guy giving the presentation that touched on this said his preference was to keep the version in the header and avoid putting it in the URL or as a query param.
Personally, we version the files themselves. We have to deploy separately versioned builds anyways, so its not much extra hassle. We just pull the version # from the Manifest and append ?{version} to the files.