Web Service Contract Versioning Fundamentals Part I: Versioning and Compatibility

Web services have made it possible to build services with fully decoupled contracts that leverage industry standards to establish a vendor-neutral communications framework. Though powerful and flexible, this framework brings with it an on-going responsibility to effectively manage those service contracts as the services continue to evolve over time. One of the most critical aspects of service governance is contract versioning. This first of two articles, comprised of excerpts from the recently released “Web Service Contract Design & Versioning for SOA” book, explores fundamental service contract issues, including compatible and incompatible versioning requirements. By Thomas Erl, David Orchard and James Pasley 

The following article is an excerpt from the new book "Web Service Contract Design and Versioning for SOA" [REF-1] Copyright 2008 Prentice Hall/Pearson PTR and SOA Systems Inc. Note that chapter references were intentionally left in the article, as per requirements from Prentice Hall.

Introduction

After a Web service contract is deployed, consumer programs will naturally begin forming dependencies on it. When we are subsequently forced to make changes to the contract, we need to figure out:

•	whether the changes will negatively impact existing (and potentially future) service consumers
•	how changes that will and will not impact consumers should be implemented and communicated

These issues result in the need for versioning. Anytime you introduce the concept of versioning into an SOA project, a number of questions will likely be raised, for example:

•	What exactly constitutes a new version of a service contract? What’s the difference between a major and minor version?
•	What do the parts of a version number indicate?
•	Will the new version of the contract still work with existing consumers that were designed for the old contract version?
•	Will the current version of the contract work with new consumers that may have different data exchange requirements?
•	What is the best way to add changes to existing contracts while minimizing the impact on consumers?
•	Will we need to host old and new contracts at the same time? If yes, for how long?

The upcoming chapters address these questions and provide a set of options for solving common versioning problems. This chapter begins by covering some basic concepts, terminology, and strategies specific to service contract versioning in preparation for what’s ahead.



Basic Concepts and Terminology

The Scope of a Version

As we’ve established many times over in this book, a Web service contract can be comprised of several individual documents and definitions that are linked and assembled together to form a complete technical interface.

For example, a given Web service contract can consist of:

•	one (sometimes more) WSDL definitions
•	one (usually more) XML Schema definitions
•	some (sometimes no) WS-Policy definitions

Furthermore, each of these definition documents can be shared by other Web service contracts. For example:

•	a centralized XML Schema definition will commonly be used by multiple WSDL definitions
•	a centralized WS-Policy definition will commonly be applied to multiple WSDL definitions
•	an abstract WSDL description can be imported by multiple concrete WSDL descriptions or vice versa

So when we say that we’re creating a new version of a contract, what exactly are we referring to?

Of all the different parts of a Web service contract, the part that establishes the fundamental technical interface is the abstract description of the WSDL definition. This represents the core of a Web service contract and is then further extended and detailed through schema definitions, policy definitions, and one or more concrete WSDL descriptions.

When we need to create a new version of a Web service contract, we can therefore assume that there has been a change in the abstract WSDL description or one of the contract documents that relates to the abstract WSDL description. How the different constructs of a WSDL can be versioned is covered in Chapter 21. The Web service contract content commonly subject to change is the XML schema content that provides the types for the abstract description’s message definitions. Chapter 22 explores the manner in which the underlying schema definitions for messages can be changed and evolved.

Finally, the one other contract-related technology that can still impose versioning requirements but is less likely to do so simply because it is a less common part of Web service contracts is WS-Policy. How policies in general relate to contract versioning is explained as part of the advanced topics in Chapter 23.

Fine and Coarse-Grained Constraints

Versioning changes are generally related to the increase or reduction of the quantity or granularity of constraints. Therefore, let’s briefly recap the meaning of the term constraint granularity in relation to a type definition. Note the highlight parts of the following example:

<xsd:element name="LineItem" type="LineItemType"/> <xsd:complexType name="LineItemType"> <xsd:sequence> <xsd:element name="productID" type="xsd:string"/> <xsd:element name="productName" type="xsd:string"/> <xsd:any minOccurs="0" maxOccurs="unbounded" namespace="##any" processContents="lax"/> </xsd:sequence> <xsd:anyAttribute namespace="##any"/> </xsd:complexType>   Example 1: A complexType construct containing fine and coarse-grained constraints. As indicated by the bolded text, there are elements with specific names and data types that represent parts of the message definition with a fine level of constraint granularity. All of the message instances (the actual XML documents that will be created based on this structure) must conform to the these constraints in order to be considered valid (which is why these are considered the absolute “minimum” constraints). The red text shows the element and attribute wildcards also contained by this complex type. These represent parts of the message definition with an extremely coarse level of constraint granularity in that messages do not need to comply to these parts of the message definition at all. The use of the terms “fine-grained” and “coarse-grained” is highly subjective. What may be a fine-grained constraint in one contract may not be in another. The point is to understand how these terms can be applied when comparing parts of a message definition or when comparing different message definitions with each other.