Sriram Anand

Subscribe to Sriram Anand: eMailAlertsEmail Alerts
Get Sriram Anand via: homepageHomepage mobileMobile rssRSS facebookFacebook twitterTwitter linkedinLinkedIn

Related Topics: Apache Web Server Journal, SOA & WOA Magazine

Apache Web Server: Article

Best Practices and Solutions for Managing Versioning of SOA Web Services

Patterns and developer techniques for service versioning

Service-oriented architecture (SOA) and Web services are being critically considered by most organizations today in some form or another. The adoption of SOA and Web services has gained momentum after the standardization of various aspects such as security, business process coordination, transaction management, communication protocol, registration and discovery, etc. However, one notable and practical aspect of designing, implementing, and managing services has not been tackled at a specification level. This aspect is related to the management of change and interface versions.

Real-world business and infrastructure services will be dynamic and subject to change due to various issues that may range from a business rules change to service-level improvement. It is a challenging problem to manage services whose interfaces are changing, especially in the situation where the number of consumers for the service is significant. In this article we present sample scenarios explaining where this problem can occur and we'll discuss detailed options with code samples to manage service versions and service changes. The options provided range from design-level techniques to specific implementation-level techniques based on emerging standards such as WS-Addressing.

SOA, Web services, version control, standards, change management

Problem Background
A service represents a unit of functionality that is described by well-defined interfaces and can be discovered by interested consumers and invoked remotely without any knowledge of the technology of location of the components that realize the specific service. SOA represents an enterprise architecture that is based on loosely coupled services that communicate with each other through well-defined interfaces through a communication medium. Web services represent the bulk of SOA implementations in the industry today. The issue of version management is an important one in the SOA context independent of the mechanism of service implementation, i.e., Web services or another approach. Therefore, let's examine some possible scenarios where this problem will be relevant.

Consider the situation in Figure 1 where we have components that perform compliance checking implemented using Web services. The business context is one that represents a typical financial services organization.

In this context, we have multiple front-, middle-, and back-office applications that are pertinent to the following lines of business: equities trading, fixed income trading, and banking. Data from these applications flow to a set of databases associated with each business application.

Back-office applications such as risk management, CRM, accounting, etc., have a critical dependency on the data from the business fulfillment applications. Compliance is a critical requirement of all financial organizations. Some of the areas in which financial services companies have to enforce compliance rules are: Sarbanes-Oxley, USA Patriot Act, and BASEL II. IT applications that implement the rules for these compliance requirements can be ideal candidates to be Web services. Implementing compliance through the use of services will allow organizations to be flexible in adapting to changes required for regulatory compliance. Apart from this benefit, on the technical side it will provide a standard way for core financial applications that are written using multiple technologies to use the compliance services (see the first entry in the References section). This briefly establishes the background for using SOA in a compliance setting. A similar rationale may be developed for reporting applications that will provide rolled-up information to management. We will not delve into the details of the applicability of SOA for these two situations in this article. We will assume that Web services have been chosen to implement these applications. Consider a situation with regards to the service for performing compliance checking.

Assume that a portType exists for performing compliance checking with respect to the USA Patriot Act. For the sake of simplicity, let's assume that this is a coarse-grained interface that is responsible for verifying the compliance of the data associated with a specific customer. Consider an interface named "checkCustomerCompliance" that accepts a customer ID as input, retrieves all appropriate data related to that customer, performs the necessary compliance checks, and returns a status back to the consumer. Given this WSDL and considering potential mechanisms by which this Web service may be changed, we can come up with the following possibilities:

  • Correcting a service implementation, e.g., a bug fix that does not involve any change to the service contract.
  • Interface modification due to addition or deletion of parameters to support an implementation change or through service enhancement. Fundamentally, this does not involve a change to the semantic contract of the old interface.
  • Service implementation change (with no change to service interface) due to change in the business rules. A specific example would be the modification of a service used for compliance checking based on a change to the compliance rules/laws.
These scenarios are discussed in more detail below with specific solution options to handle each type of change.

Options for Handling Service Changes
Implementation Change
As mentioned above, this type of change is strictly related to the rectification of errors in a service implementation that does not include a change to the external service interface. Therefore, in principle, consumers of this service would be completely unaware of any change to the service whatsoever. This type of change is fairly easy to manage given the fact that the consumer, in principle, is getting a service that is closer to the contract that has been specified. The options to manage this type of a change are therefore quite simple and can be detailed as below.

One fairly trivial option that can be adopted is to simply deploy the corrected service implementation and decommission the original service implementation. The modified implementation would then be bound to the original service-interface definition. Obviously there are other considerations that accompany this, such as performing the deployment without impacting users who are currently accessing the service during the time of this deployment, but we will not address those issues in this article.

Version Number
The second and more involved approach to handle this situation is using a change identifier. This approach may be realized by using the identifier in the service interface headers. This identifier can provide a predefined measure of the change in a specific interface. By predefined we mean that the service documentation will enumerate the different values that the identifier can take. Consumers of the service should be capable of obtaining the interface change details. The identifier can be valid for a specific period of time after which its value will be reset, thus completing the process of notification of consumers. To provide a specific example, consider a service named "getUSSales" that is responsible, as the name indicates, to provide a rolled-up report of all US sales by polling the appropriate databases. Assume that the query that was used in the service implementation to query one of the databases was wrong and was subsequently corrected. As a part of the service definition, a parameter may be defined as follows:

<message name="USSalesResponse">
    <part name="change_detail" type="xsd:string"/>
...other parameters...

In this example, the parameter "change_detail" may be a concatenation of two numbers, one indicating whether the service has changed or not, and the other indicating the change reference number (like a bug-tracking number for example). The WSDL and SOAP (generated from apache AXIS) shown in Listings 1 and 2 contain a part-in-message element to indicate version number and the response generated from such a service.

Modified Implentation Version
The third option that is available is to maintain the old interface and define a new implementation. The interface can be bound to the modified implementation as well and the version information may be provided via the SOAP headers. It would become the responsibility of the calling applications to interpret the version number. The calling application needs to include a header element in the SOAP request that indicates the required version number of service implementation. In case the requested implementation is not the most recent one, the service includes a SOAP header element that indicates the most recent version available.

This method will require multiple implementations of the interface to be active at the same time. The behavior of the service that depends on the header can be described in human-readable format using the documentation feature in WSDL. The polymorphic behavior can be achieved either by having more than one implementation of the interface or by implementing a new service and diverting the requests based on SOAP headers.

More Stories By Sriram Anand

Dr. Sriram Anand is a principal researcher at Infosys Technologies, Bangalore. Prior to joining Infosys he worked in IT consulting as well as product engineering in the US for over 12 years. His interests include enterprise architecture, service-oriented architecture, and legacy integration and software engineering methodologies. Dr. Anand is experienced in designing enterprise architectural strategy for leading U.S. companies in the financial services, retail, and pharmaceutical domains. He holds a Bachelor?s degree from IIT-Madras with a PhD from SUNY-Buffalo, USA.

More Stories By Krishnendu Kunti

Krishnendu Kunti is a senior technical specialist with the Web Services Center of Excellence at Infosys Technologies, Hyderabad. He has contributed to architecting, design, and testing of Syndeo, an in-house service-oriented platform for enterprise-grade deployment of Web services. His areas of interest are SOA and business execution languages. Currently he is working as a technical lead at a leading financial services company developing data services using SOA.

More Stories By Mohit Chawla

Mohit Chawla is a software engineer with the Web Services Center of Excellence at Infosys Technologies, Hyderabad. His primary area of interest is SOA, with a specific focus on Web services implementations on various platforms. He is also interested in developing applications using emerging WS-* standards. His current is currently focused on SOA-based enablement of legacy systems.

More Stories By Akhil Marwah

Akhil Marwah is a software engineer with the Web Services Center of Excellence at Infosys Technologies, Hyderabad. His current area of focus is Web service implementations using Microsoft Technologies, specifically the MS .NET framework. He is also interested in developing Web service applications using the J2EE stack. He is currently working on areas related to SOA-based enablement of legacy systems.

Comments (2)

Share your thoughts on this story.

Add your comment
You must be signed in to add a comment. Sign-in | Register

In accordance with our Comment Policy, we encourage comments that are on topic, relevant and to-the-point. We will remove comments that include profanity, personal attacks, racial slurs, threats of violence, or other inappropriate material that violates our Terms and Conditions, and will block users who make repeated violations. We ask all readers to expect diversity of opinion and to treat one another with dignity and respect.