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.
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|
|•||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?|
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|
|•||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|
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"/>
Example 1: A complexType construct containing fine and coarse-grained constraints.
(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)