Microservices Expo Authors: Liz McMillan, Pat Romanski, Carmen Gonzalez, Elizabeth White, Jason Bloomberg

Related Topics: Microservices Expo

Microservices Expo: 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.

Microservices Articles
Modern software design has fundamentally changed how we manage applications, causing many to turn to containers as the new virtual machine for resource management. As container adoption grows beyond stateless applications to stateful workloads, the need for persistent storage is foundational - something customers routinely cite as a top pain point. In his session at @DevOpsSummit at 21st Cloud Expo, Bill Borsari, Head of Systems Engineering at Datera, explored how organizations can reap the bene...
"NetApp's vision is how we help organizations manage data - delivering the right data in the right place, in the right time, to the people who need it, and doing it agnostic to what the platform is," explained Josh Atwell, Developer Advocate for NetApp, in this SYS-CON.tv interview at 20th Cloud Expo, held June 6-8, 2017, at the Javits Center in New York City, NY.
The Jevons Paradox suggests that when technological advances increase efficiency of a resource, it results in an overall increase in consumption. Writing on the increased use of coal as a result of technological improvements, 19th-century economist William Stanley Jevons found that these improvements led to the development of new ways to utilize coal. In his session at 19th Cloud Expo, Mark Thiele, Chief Strategy Officer for Apcera, compared the Jevons Paradox to modern-day enterprise IT, examin...
In his session at 20th Cloud Expo, Mike Johnston, an infrastructure engineer at Supergiant.io, discussed how to use Kubernetes to set up a SaaS infrastructure for your business. Mike Johnston is an infrastructure engineer at Supergiant.io with over 12 years of experience designing, deploying, and maintaining server and workstation infrastructure at all scales. He has experience with brick and mortar data centers as well as cloud providers like Digital Ocean, Amazon Web Services, and Rackspace. H...
Skeuomorphism usually means retaining existing design cues in something new that doesn’t actually need them. However, the concept of skeuomorphism can be thought of as relating more broadly to applying existing patterns to new technologies that, in fact, cry out for new approaches. In his session at DevOps Summit, Gordon Haff, Senior Cloud Strategy Marketing and Evangelism Manager at Red Hat, will discuss why containers should be paired with new architectural practices such as microservices ra...
In his session at 20th Cloud Expo, Scott Davis, CTO of Embotics, discussed how automation can provide the dynamic management required to cost-effectively deliver microservices and container solutions at scale. He also discussed how flexible automation is the key to effectively bridging and seamlessly coordinating both IT and developer needs for component orchestration across disparate clouds – an increasingly important requirement at today’s multi-cloud enterprise.
The Software Defined Data Center (SDDC), which enables organizations to seamlessly run in a hybrid cloud model (public + private cloud), is here to stay. IDC estimates that the software-defined networking market will be valued at $3.7 billion by 2016. Security is a key component and benefit of the SDDC, and offers an opportunity to build security 'from the ground up' and weave it into the environment from day one. In his session at 16th Cloud Expo, Reuven Harrison, CTO and Co-Founder of Tufin, ...
DevOps is often described as a combination of technology and culture. Without both, DevOps isn't complete. However, applying the culture to outdated technology is a recipe for disaster; as response times grow and connections between teams are delayed by technology, the culture will die. A Nutanix Enterprise Cloud has many benefits that provide the needed base for a true DevOps paradigm. In their Day 3 Keynote at 20th Cloud Expo, Chris Brown, a Solutions Marketing Manager at Nutanix, and Mark Lav...
Many organizations are now looking to DevOps maturity models to gauge their DevOps adoption and compare their maturity to their peers. However, as enterprise organizations rush to adopt DevOps, moving past experimentation to embrace it at scale, they are in danger of falling into the trap that they have fallen into time and time again. Unfortunately, we've seen this movie before, and we know how it ends: badly.
TCP (Transmission Control Protocol) is a common and reliable transmission protocol on the Internet. TCP was introduced in the 70s by Stanford University for US Defense to establish connectivity between distributed systems to maintain a backup of defense information. At the time, TCP was introduced to communicate amongst a selected set of devices for a smaller dataset over shorter distances. As the Internet evolved, however, the number of applications and users, and the types of data accessed and...