Web Services - Versioning Practices

Before jumping to versioning of web service, I like to point out that a service has two parts:

1. Implementation: This part may be Java/C#/etc code specifically written for a service under consideration or legacy code & wrapper written over it.
2. Interface: This part is WSDL file in WS* ecosystem or a simple HTML in case of REST world.

Keeping this background in view versioning of a web service can be done at two levels.

1. At implementation level
2. At interface level (This blog entry focuses on WS* complaint web services only. So WSDL versioning will be discussed).

With versioning comes compatibility. Compatibility should be considered from service view as well as consumer.

Compatibility from Service View:

1. Backward compatibility: New version of the service remains compatible with older consumers who were compatible with older version of the service.
2. Forward compatibility: New version of the service remains compatible with future consumers independent of their compatibility with older version of service.

Compatibility from Consumer View:

1. Backward compatibility: Customers of newer version of the service remain compatible with older version of the service.
2. Forward compatibility: Consumers of older version of the service remain compatible with newer version of the service.

Versioning of a service does not emerge from zero. The requirement of versioning of a service emerges due to change in some feature of it. This feature may be due to change in:

1. Functionality
a. Technical – enterprise is changing technology A to B
b. Business – Address Service supplies alternative address in addition of business & home address
2. Quality of service – add one more level of QoS service (existing one are Platinum & Gold; newer one is Bronze)
3. Deployment scenario – change in endpoint, out sourcing of service

These changes can be of following types:

1. Incremental : functionality & features are added to service
2. Decremented: functionality & features are deleted from service
3. Transparent: Consumer do not care about changes. They continue to live in their own cozy world without caring changes in services which they are consuming as they are not affected by changes in the services.
4. New Emergence: New service has arrived in the wild.

An SOA or Service architect has to deal with all of these parameters which can affect service or consumer and which lead to versioning.

The easiest way to handle versioning of the services is to “not to care about it”. Just create a new service every time. This approach seams simple but will lead to the situation where enterprise will host several service which essentially giving same output with slight variation. Consumers are confused; they do not know which service to call. Bloated maintenance and support staff. Ever increasing service portfolio, without significant increase in functionality to be offered via services.

If business users of your organizations are happy and content with case, STOP reading, you do not need to know the details to avoid this mess.

Let us list all possible combinations.



To handle versioning in WSDL there are two approaches

1. Context based
2. Content based

The consolidated list of changes which can occur in WSDL is:

1. Change in the operation/s parameter/s of a Web service.
a. Addition of new input parameter/s (this will affect the current consumers)
b. Change in existing input parameter/s
i. Change in an XML document that might be used as a message parameter in a Web service. The changes in an XML document may involve the addition of optional elements or attributes (this might affect the current consumers) or of mandatory elements (this will affect the current consumers)
ii. Change in data type or order (this will affect the current consumers)
2. Addition of operation/s
3. Deletion of operation/s (this will affect the current consumers if deleted method is under use by any of existing consumer)
4. Change of the name of operation/s (this will affect the current consumers)
5. Change in structure of complex data type
6. Addition/Deletion of elements to existing response message
a. Required elements (this will affect the current consumers)
b. Optional elements (this might affect the current consumers)
So, how to do versioning?

1. Place the version number in the WSDL target name space.



2. Version the import types in WSDL



3. Embed versioning info in the interface (portType) name



4. Embed versioning info in the service name



5. Use UDDI as a Version aware registry
6. Provide one operation per WSDL which returns info about
a. Version of called WSDL
b. Status of current WSDL (deprecated or otherwise)
c. End point of latest WSDL
d. Version of latest WSDL

To handle versioning challenge following patterns can be used

1. Consumer binding pattern
2. Layer of indirection pattern
3. Adapter pattern