Service Versioning for SOA

SOA Magazine, 2006

READS: 37,497

Policy-based version control for SOA services

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 life-cycle 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: Is SOA a structure of interfaces such as Web Services or it is a structure of services with interfaces? Who is the master in SOA – the client or service (provider)? Is an immutable interface more important to a client than the service behind the interface? What does a version of a service interface mean in case if it’s backward compatible or if it’s not? Should a client know if the nature of the service has been changed behind its immutable interface? 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

[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.

Controlling Version Compatibility
As I mentioned, we’re looking at the SOA service versioning from the client’s perspective. The version control procedure may be easier understood if we assume following principles:

1)  A client engages a SOA service on the basis of a Service Level Agreement. That is, a SOA service represented by, for example, its Web Service interface, is invoked not when WSDL is available but when the client is fully aware of the service behavior and conditions. The latter includes a service version model and the corresponding interpretation of currently available service functionality. I’m happy to note that Thomas Erl also supports the concept of a versioned SLA that may include separate information about the endpoint, service, and interface. I discussed SOA service SLA in another article published in SOA Web Services Journal (vol. 6, issue 5).

2)  The compatibility between client needs and service functionality is expressed via a Version Control Policy (VCP). It’s a set of rules that decide whether a particular version of the service is adequate to the client’s needs and can it be used according to the SLA. The simplest case of the VCP is a single-rule policy saying that the service version has to be matched (be equal) to the version identifier represented in the client’s request. You, probably, recognize the traditional API version usage in this case.

3)  The service version change doesn’t automatically modify the VCP. To accumulate a backward-incompatible version change, the rule(s) in the VCP have to be explicitly changed. It’s assumed that the VCP is written in a way that it can automatically cover backward-compatible version changes.

For the sake of simplicity, let’s assume that the version elements are numeric. Other syntaxes are also possible but require additionally defined “operations” of the version element values. So, our example of a service version is 1.3.12.123456789045678905678 and the client’s VCP rules are:

• Rule 1: IF srv ‘EQ’ 1
• Rule 2: IF nbc ‘LE’ 2
• Rule 3: IF bwc ‘GE’ 9
• Rule 4: IF rel ‘GE’ 123456789045678900001 where ‘EQ,’ ‘LE,’ ‘GE,’ ‘LS,’ ‘GT,’ and ‘NE’ are Boolean expressions such as “equal,” “less-and-equal,” “greater-and-equal,” “less,” “greater,” and “not-equal” respectively.

The VCP states, for example, that the service version is compatible with the client’s needs when all rules are satisfied. In the example, Rule 2 is violated. This means that:

1)  The client may not use the service of a particular version;

2)  The client’s VCP has to be reviewed and rule(s) have to be adjusted to accept the service version. It’s important to notice the adjustments may be done only if the new version meets the client’s business requirements.

In some cases, the client’s business requirements get into conflict with new service version and the client should continue using the previous version of the service. At the same time, if the client team knows what business features are to be provided in the coming/future versions of the service, the VCP can be set in a way that permits service invocation even when the new versions aren’t backward compatible. For example, Rule 2 may be redefined as nbc ‘LE’ 5. That is, the current and two consecutive service changes that aren’t backward compatible meets and will meet the client’s business requirements. With such a VCP, the client can work without interruption even when versions change.

Thus we deal with the service version and the VCP. The service version belongs to the service; it may be accessed at the point of service announcement/registration. For example, for the service with a Web Service interface, it may be a UDDI; for a RMI interface, it may be an RMI registry; for other services, it may be JNDI/LDAP, or the CORBA directory service, or Microsoft Active Directory, or others. The VCP belongs to the client. To control policy preservation, we need a policy enforcement component (PEC). The PEC belongs either to the client or to the point of service invocation/announcement/registration. Irrespective of location, a client can register its VCP for a particular Service with a PEC.

Hopefully, you’d agree that SOA service invocation from a business perspective is a little bit more complex than just WSDL discovery with this or that version of the endpoint. To simplify a SOA service control, the PEC could always be set at the announcement/registration point and might be implemented as a PEC service. If a request for service returns something like a “not available” exception, it means there’s no version of the service meeting the related VCP; the client might have to evaluate/consider a new version and adjust the VCP.

An independent PEC-based approach differs from the so-called “Service Versioning Covenant” model. The latter assumes that every service has its covenant, which governs all coming requests (messages and method calls) with regard to version compatibility. The covenant controls whether the request is done for the available version and simply refuses mismatching requests. The client doesn’t have information about what version of the service component is behind the interface. The consequences are: the performance of the client requests degrades due to repeated controls, the client never knows if the next request will be denied due to a change in the service version, the client never knows if the new service version is suitable for it. Moreover, since every service can have different cycles for version changes, a service composition (a structure of services working with each other according to a scenario) may become broken at any moment. Thus, such a service-centric version control appears inefficient.

Version Control Layout
Figure 1 shows two ways of controlling the version of the service. The first way the service reference is obtained from the Service Registry and invoked. The PEC intercepts every invocation call. The PEC has to acquire the service’s version from the service provider, apply a related VCR, and decide if an invocation is permitted. Since all service providers are free to define their own version models and mechanisms for accessing version information, the PEC has a quite challenging task. Plus, an in-call control degrades call performances.

The second way the PEC works in the Service Registry. The PEC validates the version information of the service at discovery time and returns the first version that satisfies the VCP. It’s important to note that version control doesn’t substitute for a functional search. If a functionally suitable service is found and the client has a related VCP, the PEC challenges the service version. However if the client doesn’t have a VCP for the service, it’s not recommended to engage the service based just on functional matching because of unknown business and technical risks.

Executing the PEC at the service registry level allows for the unification and formalization of the compound version model and version control mechanism. Unified rules and version formats can be shared between all users and vendors of the service registry. Validation of the version before service invocation works for in-call performances and prevents wasting resources on incompatible calls. So, let’s see what we can do for a service registry to represent a compound service version.

Finding the Version of the Service
Released SOA services are usually registered in different registries as mentioned. For example, assume we have an EJB-based service. The service has two interfaces – Web Service (J2EE 1.4) and RMI/IIOP; the Web Service interface is registered in a UDDI and the RMI/IIOP is registered in a JNDI directory. To a client it’s the same service providing the same business function so there should be an interface-independent service version available in both the UDDI- and JNDI-based registries.

As we know, UDDI has a special structure that permits registering the interface, usually defined by the <overviewURL> element, separately from registering the service component defined by the <businessEntit> element. Binding between the service component and its Web Service interface is specified in the <bindingTemplate> element, which is hidden inside the <businessEntit> element. Such a model causes discovery issues not only for the Web Services themselves but appears as an error-prone approach to SOA services because it allows registering the interface without registering the service component. Looking at a service registry from the client’s perspective, the service features and the SLA are the primary interests while the service interface and the vendor name are secondary. Unfortunately, we don’t have a real alternative to UDDI so far.

Using a UDDI taxonomy, i.e., its tModel concept, we can create and, via the UDDI API, register as many version entries as we need for a particular SOA service. The version entry may carry additional information about its state like “current” or “deprecated.” Every vendor can specify its version namespace and use “version name” and “version information” accordingly. Since a VCP is created for a particular service, the client is aware of related version namespace and the version information can be actively utilized. Listing 1 is an example of a version namespace definition in a UDDI.

When the service version is in the UDDI, both the service component entry and its interface entry have to refer to the “uuid:whatever_key_for_theCompanyName_version_entry” and specify their version in the <keyedReference> element of the <categoryBag> element. Listing 2 offers an example of a version reference in an interface entry.

The definition of a version namespace allows a vendor to provide a strong naming convention regarding the keyName and keyValue. Until it is standardized, we can expect different vendors to define the different version namespaces the clients have to deal with differently. At least, for one company, the version namespace may be unified at the enterprise level and simplify the life of enterprise clients.

In spite of the version namespace definition, we inherit the UDDI problem and encounter the risk of having only one entry with a certain version value instead of two – for the interface and for the service component – in the service registry. I suggest this risk can be mitigated by a PEC service until a UDDI provides an appropriate control.

Talking about EJB and JNDI, we have to distinguish between service and application types of the versioning models. For applications, version control can be done at the build and deployment stages via, say, Manifest files specified in the application archives (Graham Hamilton of Sun Microsystems offered more information about versioning and dependency mappings for Java applications at the last JavaOne conference). For services, we have no more choices than we discussed before – controls on every invocation or controls at the lookup of the EJB reference (Home interface). Since the former may be ineffective, we’ll concentrate on the latter.

The deployment descriptor of an EJB or an RMI service defines a JNDI name that the component reference is bound to. Looking at the name structure, one can easily find that a JNDI name represents a hierarchy of names. This means that a lookup operation performed, for example, by a Service Locator module (see Service Locator pattern) can explicitly navigate along the name-tree instead of making a single call on the composite JNDI name. So the JNDI name may have an immutable version part and a changeable version part. The Home interface or service reference binds to the changeable version part, which is a child of the immutable service part in the naming hierarchy. The example in Figure 2 demonstrates the version name hierarchy for the following versions:

Thus, doing a lookup operation, the client’s Service Locator represents the immutable service part of the JNDI name to the PEC. The latter navigates to all the children of the immutable service part – the names in the changeable version part – combines possible version expressions, and challenges them against the VCP. The service reference bound to the first found ‘matching’ combination of version names is returned. The client’s code can cache the reference and reuse it in consecutive RMI service invocations or for narrowing the Home interface reference to the EJB Object interface references.

If a service provider discards an RMI service, the service invocation returns an exception. It’s recommended to make at least one attempt at obtaining another RMI reference under the previous VCP before reporting an error (because the service may be redeployed). If the EJB is redeployed under the same JNDI name, narrowing always returns the current reference to the Object interface transparently to the client. If the service invocation fails under the same VCP, it may mean that the previous version isn’t supported anymore. So the client has to do a business review of the new version of the service and, if possible, adjust its VCP.

Conclusion
This article promotes the idea of a SOA client viewing a SOA service as a monolithic entity with an easily interpreted compound version. A compound version can hide multiple versions of service components and separate versions of elements of the Web Services representing the service interface. The proposed version model and an approach to the version control based on the client’s version policy open a way for flexible version management even for changes in the SOA services that aren’t backward compatible. Compound version specification is illustrated for a UDDI and a directory structure. The example shows two ways of applying the policy enforcement mechanism and promoting policy control at the service registry for service lookup operations.

References

• UDDI Core tModels.www.uddi.org/taxonomies/Core_Taxonomy_OverviewDoc.htm
• Liang Yu. “Understanding UDDI’s tMode.”www.codeproject.com/soap/understandingTModels.asp
• Kyle Brown and Michael Ellis. “Best practices for Web Services Versioning.” www-128.ibm.com/developerworks/webservices/library/ws-version/
• Chris Peltz and Anjali Anagol-Subbarao. “Design Strategies for Web Services Versioning.” http://webservices.sys-con.com/read/44356.htm
• Kirk Allen Evans’ Blog. “Versioning Web Services.”http://blogs.msdn.com/kaevans/archive/2004/12/03/274271.aspx
• Heather Kreger. “A Little Wisdom about WSDM.” www-128.ibm.com/developerworks/webservices/library/ws-wisdom/
• Thomas Erl. “The Principles of Service-Orientation Part 2 of 6: Service Contracts and Loose Coupling.”http://searchwebservices.techtarget.com/tip/1,289483,sid26_gci1171966,00.html
• WSDM-MOWS 1.0 specification, Draft. www.oasis-open.org/committees/download.php/5664/wd-wsdm-mows_versioning_change_2.23.04a.doc
• Don Smith. “[Web] Service Versioning Guidance.”http://blogs.msdn.com/donsmith/archive/2006/01/31/520338.aspx
• Rocky Lhotka. “A SOA Versioning Covenant.”www.theserverside.net/news/thread.tss?thread_id=33434
• Service Versioning. http://orchestrationpatterns.com/serviceVersioning?PHPSESSID=4dee379138a5d1f6b59e02468f2ef0ec
• Dragos Manolescu and Boris Lublinsky. SOA Enterprise Patterns – Services, Orchestration and Beyond. Book Draft.http://orchestrationpatterns.com/files/ServiceVersioning.pdf
• Java Futures at JavaOne: www.theserverside.com/news/thread.tss?thread_id=40569