BT

Facilitating the Spread of Knowledge and Innovation in Professional Software Development

Write for InfoQ

Topics

Choose your language

InfoQ Homepage Articles Web Service Contract Versioning

Web Service Contract Versioning

Bookmarks

Today we introduce the book “Web Service Contract Design and Versioning for SOA” by Thomas Erl, Anish Karmarkar, Priscilla Walmsley, Hugo Haas, L. Umit Yalcinalp, Canyang Kevin Liu, David Orchard, Andre Tost, James Pasley. More exactly, chapters 20, 21, and 22 of the book addressing the issues related to service contract versioning.

Download: Web Service Contract Design and Versioning for SOA – Chapter 20, 21, and 22 – Service Contract Versioning (PDF)

Web services in a SOA-based solution need detailed, technical contracts which clearly specify what each service is meant to do and how is to be used. Since services are subject to change over time, the contract designers need to make sure service consumers use the appropriate variant of the contract, problem solved through versioning.

Chapter 20 - Versioning Fundamentals

In this chapter, the authors present the basic concepts and terminology used in versioning, compatibility issues to be addressed, how to use version identifiers, and several versioning strategies one could choose from.

Since a web service contract can be made up of multiple documents - WSDL definitions, XML Schema definitions, WS-Policy definitions – versioning should apply to all documents that change when the contract changes. Usually, the WSDL versioning is considered, but it is possible changes to appear in XML Schema definitions too, so they also need to be versioned.

There are 4 fundamental types of changes that need to be considered: backward compatible, forward compatible, compatible and incompatible. This section explains each type of change accompanied by examples.

The next sections present the most common versions identifiers used and versioning strategies. Three strategies are detailed:

  • Strict – Any compatible or incompatible changes result in a new version of
    the service contract. This approach does not support backwards or forwards
    compatibility.
  • Flexible – Any incompatible change results in a new version of the service contract
    and the contract is designed to support backwards compatibility but not forwards
    compatibility.
  • Loose – Any incompatible change results in a new version of the service contract
    and the contract is designed to support backwards compatibility and forwards
    compatibility.

Chapter 21 - Versioning WSDL Definitions

In this chapter, the authors deal with versioning of WSDL definition documents using the “significance of change” approach and the documentation element. Beside versioning the entire document, the book contains examples of versioning the operations definitions, the port type definitions, and the concrete descriptions.

Chapter 22 - Versioning Message Schemas

The XML Schema definitions contained by a service contract represent the basis for input, output and fault messages exchanged during service use. As a consequence, the authors consider that XML Schema definitions are most often subject to change and in need of versioning.

The chapter explains what XML Schema components are, their content sets, and the effects of adding/removing/renaming/modifying components and their relationship to versions. The authors also explain how changes of the XML Schema target namespaces affect the WSDL target namespaces and how to apply strict, flexible and loose versioning in such cases. 


These chapters are excerpted from the book Web Service Contract Design and Versioning for SOA, authored by Thomas Erl, Anish Karmarkar, Priscilla Walmsley, Hugo Haas, Umit Yalcinalp, Canyang Kevin Liu, David Orchard, Andre Tost and James Pasley, published Sept. 2008 by Prentice Hall Professional as part of The Prentice Hall Service-Oriented Computing Series from Thomas Erl, ISBN 013613517X, Copyright 2009 SOA Systems Inc. For more info, please visit informit.com/soa or soabooks.com

Rate this Article

Adoption
Style

BT