Backwards compatibility and Web Services

Question

So I'm a bit new to web services and a situation recently came up where we added an element to a data-type that gets returned to the client. The clients complained that this broke their implementation because it choked on the new element that it did not expect. (we are providing the services via Axis2).

To me this seems like a harmless change that the client should be able to handle gracefully (I've worked with some non-web-service frameworks where adding optional information was completely acceptable). I could understand if we deleted or renamed some fields that that would cause issues for the client.

Basically I would expect the wsdl to act like an interface. If we make a change that essentially subtypes that interface, I would expect the client to happily ignores extraneous elements. Is this just a short coming of web services, or is there a sane way of making passive changes to the services so that new clients can get the extra data while old clients can update at their leisure?

Answer 1

In the past, when dealing with exposed WebService APIs, I've always gone with the date-versioning philosophy. Unfortunately, you have to deal with backwards compatibility for any API you release to the public once you're out of "beta" mode (and sometimes even then).

What we did was really simple; on the day the new API was released, we'd create a folder structure like so:

http://mydomain.com/path/to/service/2009/12/17/servicename.svc

That way we would know which version was the latest just by checking the folder structure, and our clients wouldn't have to worry about breaking changes until they were ready to upgrade. Worked like a champ for us; the only thing I might have changed was to use a single folder so they'd be easier to view all together:

http://mydomain.com/path/to/service/2009-12-17/servicename.svc

Answer 2

WSDL actually acts as a contract more than an interface. The WSDL describes exactly what the operation expects to "receive" and what it expects to "return". The closest analogy to this would be in C changing the prototype for a function without changing the function itself, they wont match and that causes problems.

The more specific the WSDL is the more behavior you are "guaranteeing" to be in place.

If you need flexibility in your returned data (i.e. adding/removing fields etc) you can do one of the following:

1. Version your WSDL definitions and publish services that can redirect older versions to newer versions
2. Use more abstract data return types, such as XML to hide the complexity or changing data.

2 has some more risk, but it can be managed with XSDs or other technologies. Your particular project requirements will dictate what is acceptable.

Answer 3

A WSDL is effectively your published SOAP interface of your web service. Many clients use this to generate their client proxies that expose all your webservice methods in their programming language of choice. Most of these code-generated clients are very fragile and will choose to throw an exception if they see an element they don't recognize (i.e. its not in the WSDL) rather than ignore it. Some are more relaxed and it is really up to the client technology they use i.e. Microsoft's new DataContract's have IExtensibleData interface on their clients to specifically hold data they don't recognize so they will largely ignore unknown elements.

SOAP and code-generated client proxies lends itself to these kind of problems because they generate clients that want to understand 'the entire schema' rather than just the bits they are interested in. The alternative is for them to use an Xml Parser and just pull out the bits that they need.

If your web service is under development or constant change then SOAP is really not your best choice as it will mean with every change they will have to regenerate, rebuild and redeploy their service clients. Depending on your situation you may want to consider providing REST+POX (Plain Old Xml) web services instead as its simpler to parse as it doesn't have the overhead of SOAP, can be called via a normal URL and by consumed by environments that don't have a SOAPClient library (e.g. directly in a browser, using AJAX)