Welcome!

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

The first option method, exposed as a Web service internally, uses a factory method to get multiple implementations of an interface, and hence a polymorphic behavior. An implementation is selected based on the SOAP headers.

The second option can be implemented by having Web service implementations of both old and new services. The Web service consumer can continue to direct requests to the old service and the requests may be diverted to the new service by using the service-level handler based on SOAP headers (see Listings 3 and 4). The multiple options are summarized in Table 1.

Recommended Option
Based on our experience, we recommend the option with the version number that will provide the information about the change to the service consumers. The service can specify a period beyond which the change identifier will not have a relevant value so that this output parameter may be used continuously for multiple changes. This option is recommended because of the level of additional work that is required balanced against the need to communicate relevant changes to service consumers.

Interface Modification
Now let's look at situations that may warrant a change in the actual service that must be communicated to the consumer, with the possibility of a change in the WSDL (specifically in the "portType," "message," and "binding" elements of a typical WSDL). The important characteristic of this type of modification is that the change needs to be communicated to all of the consumers of the question without fail in order to ensure compliance with the SLA. This change may arise due to one of a few different reasons such as correcting an implementation as mentioned above or making a planned enhancement to the service based on requests from consumers simply to support modified business rules. Consider a compliance service such as the aforementioned "checkCustomerCompliance" service. In the event of a legislative change in compliance rules, this service would require modification that may precipitate changes to both interface as well as to implementation. As a specific example, assume that the aforementioned service is responsible for retrieving a customer data and then running specific checks based on the regulations under the Patriot Act entitled "Money Laundering." Assume that at a later point in time, the regulations are modified in some way that requires the compliance checking to be provided with additional information. This situation would result in the change to the service as discussed above. There are several approaches to handle a service interface that is subject to this type of a change, and these options are discussed below. These options may be broadly classified into two groups. One set of options uses version management techniques without requiring any additional technology implementations. The other set has a dependency on UDDI and the implementation of a UDDI directory. The options are discussed in additional detail below.

New Interface
The first and most obvious option that comes to mind is the creation of a brand new interface, regardless of whether the old interface may be reused or not. Note that under certain circumstances the old interface may be reused, especially if existing parameters are being deprecated. For example, assume that we are considering a situation with the WSDL snippet (sample WSDL for sales) provided below.

<message name="checkCorporateSalesResponse">
    <part name="line_of_business_id" type="xsd:string"/>
...other parameters...
</message>

Let's assume that due to reorganization within the company, this service is responsible for only returning the sales associated with a particular geographic region. One option to align the service with the requirement change is to add a parameter that specifies the geographical unit for which the sales are required. However, this may need to be implemented carefully because existing consumers of the service would get incorrect information if the implementation were performed in a transparent manner. The existing interface will need to be retired to prevent consumers from getting outdated functionality. This may be accomplished by throwing a fault on the old interface that redirects the user to the updated WSDL. In addition, the change identifier concept mentioned above can be used with a special value that indicates a "retired" interface. The service implementation can return the change identifier for a specific period of time after which the service, including both interface and implementation, may be decommissioned.

Stateful Web Services
Consider the situation of a service that is stateful and that is implemented in a manner that the service implementation is aware of the consumer. This type of implementation is rare and this option has been discussed here for the sake of completeness. For this type of a service there is the option to track information provided to a service consumer. Therefore, an approach similar to the change-identifier method may be used along with the implementation of a new interface. In this method, the service output may be modified to add an element that contains information on the change. The consumer-calling interface is also augmented with an element that provides an acknowledgement to the service implementation about the status of the message received. This mechanism can be used as a programmatic method of communication between a service producer and service consumer on issues that are extraneous to the actual functional implementation. Once a service consumer acknowledges the receipt of a change, the data may be used to track the number of consumers who have been made aware of a specific interface change, and subsequently the interface may be retired. Once a specific consumer is informed of a change, no additional information about this specific change needs to be sent.

XML Namespace
The concept of XML namespaces may be used to provide a different mechanism for handling interface change. Recall that the "targetNamespace" attribute of a schema is used to provide a scoping mechanism in XML; therefore, this attribute may be used to identify changed interfaces. The convention used for naming the namespace may be predefined and communicated to consumers through the service documentation. One simple approach may be to add a version number to the original namespace URL. Alternatively, a timestamp may be used to augment the URL. Take a look at the WSDL snippet shown in Listing 5. Consider a change to this WSDL similar to the aforementioned change to add the geography as an additional filter for getting the sales pertinent to specific locations. In this case, we may indicate the modification by changing the namespace attribute to something as follows:

targetNamespace=http://www.mydomain.com/webservices/
salesreport/CorporateSales_v1.1.wsdl

or

targetNamespace=http://www.mydomain.com/webservices/
2005/01/05/salesreport/CorporateSales.wsdl

In the second example, the versioning is accomplished by placing the WSDL scoped by the timestamp of the change. Requests associated with the previous version of the WSDL, i.e., those that are associated with the older namespace, may be handled by a couple of different options. One straightforward option is be to generate an error on the server and provide data to the user on the new implementation. This approach would result in service consumers having at least one guaranteed failure per service change during service invocation. Therefore, if a service undergoes multiple modifications within a short time frame, this can lead to poor quality of service delivered to the consumer. This scenario is quite realistic in the case of service implementations for common functionality, e.g., data access in a large company. Typically these services are designed to accommodate all consumers, but evolving needs of multiple areas of the company may require frequent modification until the services are "stabilized" and adopted throughout the company. In this situation, a more graceful approach may be to provide an intermediate Web service that can accept requests and then make a decision to forward the request to the correct implementation based on the timestamp rules. This would not add a significant amount of overhead to the existing implementation and it may be the preferred option given the expected frequency of service changes.

Complex Type (SOAP Response)
An additional option for communicating a specific change to a service consumer is the use of a SOAP response element. In such a scenario some predetermined tags in the SOAP response are used to convey the information. The SOAP response should be some complex type that contains version information along with response parameters. The analog to a complex type can be a class in the Java programming language, for example. This type can be composed of any constituent elements. Therefore, we could conceivably have an element that is dedicated to storing the version of a particular interface. Consumers of the service may retrieve the data in the complex type and interpret it for detailed information on the characteristics and "age" of the particular service. This element is returned instead of an actual response in case the version of a service has changed. This approach allows for significant flexibility in communicating changes to a service consumer. Listing 6 shows a snippet from a WSDL to help illustrate this better.

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.