Web Services Versioning

You’ve developed the killer web service for your own consumption. You thought that sharing it with others would have been the best thing to do…You give out the WSDL and now, your service consumers are loving it!

Weeks and months went by, you need to enhance the application and ripple some of the changes to your killer web service. Now what?

Two types of changes

There are (backward-) compatible changes and there are incompatible changes.

Examples of compatible ones (these are typically additive changes):

Abstract Definitions

• adding new optional XML schema element or attribute declaration to an existing message definition

<xsd:complexType ...>
   <xsd:sequence>
      <xsd:element .../>
      <xsd:element .../>
      <xsd:element ... minOccurs="0"/>
   </xsd:sequence>
</xsd:complexType>

• adding wildcards (i.e. xsd:any or xsd:anyAttribute) to an existing message definition

<xsd:any namespace="##any" processContents="lax" minOccurs="0" maxOccurs="unbounded"/>
<xsd:anyAttribute namespace="##any"/>

• adding new WSDL port type definition and associated definitions

<portType name="original"> ... </portType>
<portType name="updated"> ... </portType>

• adding new WSDL operations to an existing WSDL and associated complex type definition for the new operations

<portType ...>
   <operation ...>
      <input .../>
      <output .../>
   </operation>
</portType>

• relaxing constraint (e.g. changing a required element to optional [minOccurs])

Concrete Definitions

• adding new WSDL binding and service definitions

<binding name="updated">
</binding>
<service name="updated">
   <port ... />
</service>

Examples of incompatible changes (these are updates):

• removing or modifying existing WSDL operations in any way (including parameter order, name of operation, etc.)
  
• modifying (including renaming) existing complex type definitions (apart from using wildcards)
  
• adding a fault message to an existing WSDL operation
  
• tightening constraint (e.g. changing an optional element to required [minOccurs])
  
• changing the MEP for an operation

 

Recommendations

For changes that are compatible, the recommendations is to use the wsdl:documentation element in the WSDL to indicate a change in the (minor) revision.

For incompatible changes, a new contract (WSDL file) needs to be created and deployed. The new contract may then indicate the (major) revision with a different (target) namespace. Most likely, the original service would still be present but deprecated until all clients have migrated to using the new contract.