Per Henrik Lausten

Consider a scenario where you have a web service that you expose to consumers - and you want to make changes to the provided web service interface. What can you change without impacting existing consumers? And how do you handle changes that do impact existing consumers? I work on a project where we have to find a solution to this scenario and my investigation of the issue lead to the following.

Based on a develeoperWorks article on Best practices for Web services versioning I have created the following list of backwards compatible changes. These changes can be implemented without any impact to existing consumers of your web service:

• Adding new operations to your web service
• Adding new XML schema types that are not contained within previously existing types
• Adding optional elements or attributes to existing request messages

However, the following are non-backwards compatible changes and require changes to be implemented by existing consumers in order to be able to use the changes web service:

• Removing an operation
• Renaming an operation
• Changing the parameters (in data type or order) of an operation
• Changing the structure of a complex data type
• Adding new required elements to existing messages
• Adding new optional elements to existing response messages
• Removing required elements

Web services versioning is required to deploy changes that impact existing consumers (unless you are able to force the consumers to use the changed web service). For backwards compatible changes the developerWorks article recommends that XML comments are used to indicate unique version IDs or a version history. For non-backwards compatible changes the article recommends the use of web services versioning based on XML namespaces that clearly identify the version of the web service:

<schema targetNamespace="http://example.com/2009/02/15/webservice" xmlns="http://www.w3.org/2000/10/XMLSchema">

An article on Design Strategies for Web Services Versioning from SOA World Magazine recommends to enhance versioning by using a hybrid solution that combines XML namespaces and version ids where the targetNamespace is used for non-backwards compatible changes while the version id is used for backwards compatible changes:

<schema targetNamespace="http://example.com/2009/02/15/webservice" version="1.1" xmlns="http://www.w3.org/2000/10/XMLSchema">

For my particular project I find the combination of namespaces and version ids to be the most useful solution as the project will introduce both backwards and non-backwards compatible changes. It will be interesting to see how this will work in practice.

Update February 16: I have clarified that adding new elements to the response message will break existing web service consumers.

Tags: versioning, web services

This entry was posted on Sunday, February 15th, 2009 at 19:58. You can follow any responses to this entry through the RSS 2.0 feed. Both comments and pings are currently closed.