Features

(Found in a blog, "Versioning is as inevitable as security.") SOA development practice isn't much different from other software development practices except for design and maintenance. Multiple self-containing and aggregated services that interact with others have their own lifecycle and evolution. The loosely coupling model of SOA services significantly simplifies design but creates additional difficulties in maintenance, especially in the interoperability of different service versions.

To better understand the requirements of SOA service versioning, let me ask several questions and see if we can answer them easily:

1. Is SOA a structure of interfaces such as Web Services or it is a structure of services with interfaces?
2. Who is the master in SOA - the client or service (provider)?
3. Is an immutable interface more important to a client than the service behind the interface?
4. What does a version of a service interface mean in case if it's backward compatible or if it's not?
5. Should a client know if the nature of the service has been changed behind its immutable interface?
6. If multiple versions of a SOA service are available, how can a client choose which one it wants or can use?

As you can see, I make a distinction between a service provider, calling it just a service, and service interface. If the service interface is a Web Service and we consider versioning, people ask what, actually, constitutes a new Web Service (WS) versus a new version of the same Web Service. Here I'll try to get some answers looking at the questions from the perspective of the SOA service client. I believe it will help us to "see the forest behind the trees."

Why Is Version So Important?
For some people this isn't a question at all. For others, it's a burden that's usually skipped in the development phase and a "sudden" nightmare during the maintenance. Let's analyze a real-life example to validate the importance of versioning in a distributed Service Oriented Architecture.

Following best practices, we had a SOA service with a coarse granular Web Service interface at one of my previous jobs. The Web Service transferred XML documents that defined "commands" (recall the well-known Command Pattern). The service provider promised to log an audit message for every command received for our review.

The provider's team wanted to upgrade its audit database and needed to block the insertion of messages for a while. The service provider built a temporary service without a logging function and silently substituted the service component under the same interface. As it happened the upgrade took longer time than planned and a lot of commands were done without audit logging. We found the problem during our audit reconciliation process but it was too late.

Now, assume that a version control is in place. A substitute (new) service component might be released only under the new version. The version-controlling utility would have to recognize this fact and either block communication or immediately notify the client about the change. You'd say that such version control defeats the interface concept of Web Services and directly affects the client even when an interface isn't changed. And you'd be right. However, in our example the Service Level Agreement (SLA) was violated by the service provider, i.e., the business of the client was affected, though the interface was preserved.

Thus, the OO practice of developing an immutable interface applied to a SOA can easily lead to a business problem. Versioning is one of the cheapest mechanisms to avoid such problems. It's not versioning the interface (a SOA service isn't an object and it has a nature, which is not addressed in object-oriented architecture) but versioning the contract between client and provider. That is, version control works for the client interests and SOA service has to honor it.

What Can Be Versioned?
There are two approaches to versioning: down-to-top and top-to-down. The former is more familiar to developers and the latter is usually used by architects and managers.

In the down-to-top approach, the attention is put mostly on the interface versioning, in particular, the Web Service. The OASIS WSDM-MOWS 1.0 draft specification says that Web Service's description, interface, service, and endpoint can be separately versioned and defined in their own individual namespaces. It's interesting to note that the final 1.0 release (as well as the 1.1 draft) don't have a version control section. That is, separate versions of Web Service's parts may be not a good idea after all.

As we know, a Web Service is defined by its WSDL. The WSDL 2.0 (draft) gets Web Services closer to the notion of a SOA service due to a new component-based concept, operational stile with restrictions and a Feature option. Following the spirit of WSDL 2.0, particular combinations of versions of WSDL elements can constitute an overall version of WSDL. Another combination of element versions leads to another version of WSDL. Unfortunately, even an overall version of WSDL doesn't answer the old question about a new version of the WSDL versus a new WSDL (i.e., a new Web Service).

For example, consider a Web Service in a document/literal style where XML Schema is imported for the message. Changes in the XML Schema don't reflect in the WSDL. So, if changes happen in the XML Schema, do we get a new Web Service? If changes are optional (e.g., new elements with minOccurs="0" is added), is it really a new Web Service for the client? There are too many questions to this version model; that's why I call them "trees."

In the top-down approach, two things are versioned: the service component and the service interface (e.g., the Web Service). The WSDM-MOWS 1.0 draft also recognizes the version of the service component and calls it a revision. According to the specification, "Revisions are related to each other via changes that happened between revisions. Each revision will be associated with a versioned component. Each change indicates a predecessor and successor (if any) revisions. Each change may aggregate multiple change descriptions."

Actually, a service component may have its own lifecycle even outside of the service realm. That is, component versioning is a standalone issue. So a compound SOA service version consists of a combination of an overall version of the service interface and a version of the service component. Our task is to come up with a definition and structure of a compound versioning model.

I've found that a single compound version concept is argumentative even for some people who agree with the aforementioned reasons. They usually refer to the "realistic requirements" stating "people care about particular method [signature] changes rather than changes in other methods." This results in dealing with individual method versions. They also refer to the practice in Java programming where the object version has "low importance" to the "people" in comparison to the version of the object's API. It's interesting though, I'm afraid, a misleading approach.

First of all, the "people" are mostly developers, not users of the service, i.e., service development cycles are the center of attention, not maintenance and integration with the clients. We, on the contrary, are concentrating on the service "face" to the clients. Second, if we follow that "realistic" approach, why bother with multi-method services when a single-method model is much simpler? The aggregation of versioned single-method services can be viewed as a container, like EJB or JMS containers, with no overall versions at all. Third, it's not quite clear (to me) what methods are meant in a case where the service interface is a Web Service in document/literal style. Are we going to version XML elements in the message? If, instead, the message is defined by a version of the XML Schema, the latter addresses multiple methods/elements together. So, we get back to the single version for all methods/elements, don't we?

I have a strong feeling the proponents of per-method versioning are trying to screw SOA services into the object-oriented realm. SOA is not a structure of RPC calls in OOA; Web Services and SOAP are no more than SOA-enabling elements but developers and vendors frequently overlook this fact. One of the major principles of SOA is business agility, i.e., agility with business processes and functions. So SOA service versioning has to be adequate to the SOA concept while the details of the interface versions or service component versions are taken care of by the service provider (e.g., via a hidden mapping of the compound version to the service elements' versions).

Compound Version Identifier
To simplify the observation of the compound version identifier (CVI) structure, let's discriminate between the version visible to the clients and the "assembly" of the versions of the individual service's components, interfaces, and elements. Nevertheless, considering the complexity of the SOA service internals, I'd like to propose that the following CVI structure be available to the services' clients (that include other services as well):

<srv>.<nbc>.<bwc>.<rel>

where

• srv is an element reflecting the major version of the service as a whole. Changes in this element represent significant changes in the service lifecycle that may be not backward compatible. For example, a security entitlement service adds a control at the level of the individual application function; it doesn't necessarily mean that access to the application has been changed but the final result may be changed without backward compatibility for particular clients;
• nbc is an element that represents a version state of the major version that's is not backward compatible for some or all of the service functions. For example, one previously deprecated function has finally been removed in that version while other functions were unchanged;
• bwc is an element indicating an extension or modification in service functionality. It's strictly backward compatible. For example, new functionality like a new type of message or a new method has been added that doesn't affect clients using old functions;
• rel is an element showing little backward-compatible changes like bug fixes. It may also be a release version correlated to the build and/or a source save repository such as ClearCase, CVS, and the like.

How this version structure helps clients recognize whether a backward-incompatible change affects them? Moreover, if the change is backward compatible or unrelated to the functionality used, should the client continuously modify connectivity code to assimilate a new version of the service? The answers to these and similar questions are in the version control procedure defining how the CVI can be used in conjunction with a client-provider contract.