Strategies for updating or versioning web services?

Question

I'm interested to hear the best practices on how different versions of web services are handled.

To clarify, if you've got some web methods exposed as a web service, then you want to add a feature/functionality and thus change the signature of those method calls, how do you handle this in a manner that doesn't break all of your clients who currently call the service?

Do you deploy the service on a different URL?

Do you put a version in the method name itself (MyMethod, MyMethodv2 etc. - ugh..)

Do you pass in a version as part of the method call along with a parameter list?

Does anyone know how Google or Amazon handle this scenario with their extensive Web Service library?

EDIT: So far I found some good info in this article from Oracle. Also this blog entry on some Java specifics was useful. I'm still curious to see some of the other approaches.

Answer 1

The typical way of versioning a web service is to have clients specify the version desired. You may allow for for simple constraints, like ">2.0", "<1.5", or "=1.1". Naturally, you want to minimize the number of supported versions for your own sanity. If a client doesn't specify a version, you assume the latest.

Techniques for providing the version vary. Some advocate using the URL, others encourage headers, some might include it as a parameter of the api call. Almost none would change the name of the method, though. Thats equivalent to the "package" or "namespace" versioning the OSGi link talks about. It'll make upgrading very difficult, and impede people from upgrading more so than any changes to the actual service.

It also depends on how you access your webservices. If you're using REST, then keeping the URL's clean and using headers makes the most sense (and it'd be trivial to hack it in as a query parameter, if need be). If you're using SOAP/XMLRPC/whatever-RPC, then putting it in the URL is usually fine.

Edit 5/2011 FWIW, though I disagree, Apigee's blog recommends putting the version in the URL.

How the client specifies the version is usually pretty easy. Whats more complicated is how you run all the versions concurrently. Most languages don't have a way of loading multiple versions of the same library/module/class/function into the same runtime environment (be it a VM, process, or what have you). The OSGi link you provided is Java's solution to allow this.

In practice, OSGi will be overkill for most situations. Its usually easier to proxy deprecated requests to another server or process.

The best way to "version" your services, though, is to build extensibility and flexibility into them so they remain forwards and backwards compatible. That doesn't mean that all versions must be compatible with each other, but consecutive versions should be compatible with each other.

Answer 2

I can tell you that the solution of creating doAPIFunction, doAPIFunctionV2, and doAPIFunctionV3, etc has produced nothing but headaches at the place I work at. Add to that the lack of clearly descriptive function names means all sorts of madness.

You want clear API function names, and if an api is changing, the goal would be to try and do so in as backward compatible way as possible. I would suggest versioning your entry points so each entry point supports a stable API and doFunction in example.org/api-1.0/ may be different than example.org/api-2.0 if there was good reason to change the semantics.