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.

Comments

Post a Comment

Popular posts from this blog

Understanding ITIL Service Management the UML way…

-
Image
I originally had a great deal of difficult reconciling the differences amongst ITIL Change Management, Incident Management, and Problem Management. Having researched on the subjects and understanding them better now, I’ve tried to put the concepts together using a UML class diagram to capture my understanding and to keep it imprinted. Similarly, I wanted to differentiate the various categories of changes (Standard, Emergency, Normal) using an easy to understand & self-explanatory manner – a UML Activity Diagram!
Read more

How to depict (Professional-Looking) Logical Network Diagrams in Astah

-
Image
I have always had to create (professional-looking) UML diagrams using Visio-like icons. You’ve got to admit that showing a bunch of boring UML boxes hardly interests anyone less technical (like anyone whose designation has the words “manager” or “director”). This is actually possible in Astah! I’ve created a template for future projects that allows me to produce logical network diagrams that look like the following: To create this diagram, you need to do the following: Assign various icons to stereotypes. I created the following for my use: Create a new UML Deployment Diagram Every element in the diagram is created as a Node The nodes are subsequently assigned the appropriate <<stereotype>>. E.g. Internet is <<internet>>, WebZone FW is <<firewall>>, Web LB is <<loadBalancer>> Ensure the “Icon Notation” is set to “Customized Icon” for each node Instead of the boring boxes, the corresponding icons automatically gets displayed!
Read more