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

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.

Answer 2

I'm not sure if i understood your question correctly. But my 2 cents. If signature of method changes like another new parameter then why can't it be made optional? But if an existing parameter data type is changed then it's not applicable.

Vote this down if it's plain wrong. :)

Answer 3

It used to be simpler when you could have the same webservice method name, and different parameters, years ago. :)

Once you write a webservice, you are making a contract with the clients that this is what you will support.

For older methods I would suggest logging to see if they are being used, and by whom, to see if you can get them to update.

Other than that you best bet is to just write a new method, so you may have several similar function names that differ by a version.

The problem with passing in a version number is that you have to ensure the clients always pass in a valid number, which, if you generate the stubs will work, but if you don't then this is very fragile.

Putting a version number in the name seems to work best for me, as it makes it obvious what is old, and you can use AOP to more easily log older versions of the webservice methods.

Answer 4

One way to mitigate this is to code by contract and by setting interfaces in stone. You can never really change function signatures, you can, however, overload them. Consider the .NET API. It deprecate some methods but they continue to work because programs coded around them may break. A new version of the service may be exposed at a different URI (v2.webservice.com) to give it a fresh roadmap and v1 would need to continue to be supported.

Answer 5

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.

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.