Thursday, May 10, 2012

Version compatibility in web service contracts

It is surprising to see how few web services are backward compatible, when a new version of the service contract is released. The result is often that all service consumers should update their client code in order to work with the new version of the service. A heavy burden for governance.

It is often stated that adding an optional field or attribute to an existing XML schema is a backward compatible change. That is, XML instance documents of the previous version are consistent with XML instance documents of the new version.

For web services, this means that request messages of the old version, will be understood by the web service, because it is consistent with the new message structure. However, for response messages, this is not true at all. The service will return a XML instance document of the new version to the service consumer, who only understands XML instance documents of the previous version. So as long as the optional element or attribute is not present in the instance document, there is no issue. But if the optional element or attribute is present, the service consumer suddenly receives some data that according to his service usage contract is invalid.

So service contract version compatibility is not the same as XML schema version compatibility.

For this work with service contracts in a general case, XML schemas must be designed both forward and backward compatible. Forward compatibility can be achieved using wildcards, which are extension points in the schema. However, such schemas become very messy after a few changes, especially for complex schemas.

Also, XML binding frameworks want ‘clean’ schemas, not the ugly ones with anyType elements, which is harder for code development. Thus, forward compatibility is often ignored in web service contract design, with versioning issues as a result. These issues are manifest in service governance.Trying to be smart and simple in service design, means we end up with complex service version governance.

Some of these governance issues can be alleviated by using a service mediator, such as a ESB, for the web service. Data transformations can be performed between interfaces of the previous version and the new version. For example, for old version service consumers, the mediator can filter out ‘unexpected’ XML instance document elements.

Another way to achieve forward compatibility would be to define service contracts using Schematron, instead of XML schema: rules-based instead of grammer-based contracts. But that's the subject of a future post.

Here are two good articles detailing some of the versioning compatibility issues:

No comments:

Post a Comment