Application versioning has always been a challenge for the developer community. With the introduction of Web services, this issue becomes even more difficult as developers are dealing with a more distributed set of components that aren't necessarily under their control.

A robust versioning strategy is needed to support multiple versions of Web services in development. This can allow for upgrades and improvements to be made to a Web service, while continuously supporting previously released versions. The right versioning strategy can maximize code reuse and provide a more manageable approach to the naming, deployment, and maintenance of your Web services.

The issue of versioning is a complicated one, and this article does not attempt to answer every question surrounding the versioning of XML and Web services. However, there are some key approaches and design practices that have been helpful in our development that we will share with you here. The approach we will take is to start at the component level (XML Schemas) and work up to higher service-level abstractions, including facades and service-oriented (SOA)–based architectures. Along the way, we hope to impart some important best practices that can be applied to incorporate versioning techniques at various levels of the design.

Let's begin by looking at the importance of XML Schemas...

The Importance of XML Schemas in Versioning
Versioning for Web services should first consider how the XML Schemas being used are versioned. A number of approaches can be taken to version XML Schemas, including using a schema version attribute, changing the physical location of the schema, and leveraging XML Namespaces.

XML Namespaces provide a scoping mechanism for XML, where elements defined in that namespace can be uniquely identified. Namespaces are typically used to reduce name collisions between schemas, but they can also be used as a version control mechanism. Here's a simple example showing how Namespaces can be used for versioning:

<xsd:schema targetNamespace=http://www.acme.com/types/pcconfig/v1

A Web service referencing a versioned schema would be required to have knowledge of the version because it is built intothe targetNamespace. The benefit of this approach is that once the targetNamespace is updated, any clients that reference it are required to do something. This automatically enforces a level of version control, requiring some action on the client's part.

The downside of this approach is that any incremental change would require the client to also change. Clearly, a noncompatible change such as removing a WSDL operation being used by the client requires client modification. But, a change such as adding an optional attribute to the schema would still be compatible with the existing code. One key question that must be addressed in your design is: What changes should constitute a new Web services version? If you take the approach that any change results in a new Namespace, this will place a great burden on the developers using the schemas.

One proposed hybrid solution is to use a combination of Namespace and version ids. The targetNamespace would only be updated for non-compatible changes. For any incremental, compatible change, the version ID attribute could be used to identify the new revision. The following approach can significantly reduce the amount of maintenance required by the developer when new versions of a Web service are released.

<xs:schema xmlns=
http://www.acme.com/types/pcconfig/v1 targetNamespace=
http://www.acme.com/types/pcconfig/v1 version="1.2">

Version compatibility can be a very difficult thing to determine. Without any robust development tools available for this, it is the responsibility of the development team to determine whether a new release maintains compatibility. In this section, we've presented a number of approaches to versioning XML Schemas. If you're considering versioning at this level of your architecture, we would recommend use of XML Namespaces in a limited capacity to indicate major version upgrades to the XML But, it is a good practice to fully test your services to verify version compatibility.

Naming Conventions for Versioning
Having a name for each release of a Web service is essential for simplifying the management of the releases. The naming strategy should facilitate recognition of multiple versions of a Web service, including both existing and new interfaces. Different strategies can be implemented here, including using a sequential naming strategy or date stamps.

When you are sequentially naming your version you can use a convention of "vMajor#.Minor#/SERVICE_NAME, where Major# is the major version release and Minor# is the minor number release. A major release would most likely require a change in the client code to use the new version, while a minor release would attempt to maintain backward compatability with the client. A minor version could constitute a modification to a Web service that would impact the internal system only.

The standard method name for a Web service has "_v#_#" appended to the end of its name. Thus, for the getProductCatalog service we might define the operation as "getProductCatalog_v1_1". Or, if you are applying this to XML namespaces, it might look like:

<xsd:schema targetNamespace=http://www.acme.com/types/pcconfig/v1/1

Another way of naming versions is to use date stamps as part of the namespace. The date helps to determine the sequencing of the version. This naming convention does not show a major or minor release. Here's how this might look in our definition of the schema:

<xsd:schema targetNamespace=http://www.acme.com/2004/03/01/pcconfig

The important thing to remember is that there isn't one best solution in how you name the versions. Your approach will depend on the deployment strategy you use and the specific requirements your clients might have to distinguish versions and maintain compatibility.

It should also be apparent that these techniques can become very unmanageable if you have to apply them to every component in your design.

To address this, let's turn to a few important design practices for building more coarse-grained services with design patterns and service-oriented architectures.

Using Web Services Facades
As organizations build, deploy, and orchestrate Web services, it becomes apparent that a higher level of versioning and management is required. You must begin thinking about services from a business level, rather than from the technical interfaces being exposed. However, many organizations investigating Web services are still looking at them as extensions to object-oriented paradigms. They make the mistake of taking their existing objects and exposing them directly with a Web services interface. This will most likely deliver Web services that are fine grained and difficult to use. It can also make it difficult to incorporate a consistent approach to Web services versioning.

Instead, think from the perspective of the WSDL first, and map to a back-end implementation later. This approach provides a more loosely coupled architecture, minimizing dependencies on specific implementations. You should also look to design patterns, such as the Web Services Facade, to assist in the creation of coarse-grained components. This pattern takes the complexity out of the interfaces being exposed. Rather than having multiple interface points to a collection of services, composite Web services can be designed with simpler, well-understood business interfaces.

As Figure 1 illustrates, the facade can be used to simplify the steps required to place a Change Order request. While this picture shows the facade being used from the perspective of the provider, a consumer of could also design facades to simplify access to services.

The use of this pattern can offer a number of benefits, including minimizing the level of coupling between consumer and service, creating a control point for manageability, and improving overall performance by reducing the number of network calls. The facade pattern can also provide a framework for managing the inherent complexity of supporting multiple Web services versions simultaneously.

One implementation of this pattern, shown in Figure 2, creates levels of abstraction by separating the code into three distinct tiers of classes: request handler classes, facade business flow classes, and business object classes.

The managing class, the session facade class, is responsible for chaining the smaller business object classes together. Each business object class contains a subunit of processing logic, and chaining of all these business object classes provides the core business logic. Each session facade class by itself contains no processing logic, but by concatenating business objects together it implements the desired business logic.

This architecture decouples processes from each other, allowing reuse of components. It also helps in managing the complexity of Web services as business requirements change in different versions of the service. Processes leveraged to execute business requirements are abstracted into individual pieces of software code that one managing class chains together to execute in sequence. By chaining these pieces of code together, required business processes are implemented to adhere to a specific business process flow. Thus, by building multiple managing classes, different business flows can be implemented and maintained simultaneously.

Importance of Service-Oriented Architectures
The design of coarse-grained services is an important aspect of a versioning strategy, simplifying the client interfaces and maximizing reuse. Designing facades at the implementation level can help, but it still requires a significant change to the underlying infrastructure at various levels that someone has to deal with. What's truly needed is an SOA-based platform that can assist in the management of the entire life cycle of Web services.

An SOA-based approach offers software components as a collection of distributed business services. A business service plays the role of a single entity that represents a business application, and may include multiple IT resources, platforms, and components. The model, simplified in Figure 3, separates the roles of consumer, provider, and registry. A provider registers available services in a registry that the consumer can later discover and invoke. Consumers aren't directly aware of a specific service endpoint or the implementation details. The SOA provides a greater degree of separation between the provider and consumer, and as changes are made to a service, the SOA can help minimize the impact on the consumer.

An SOA typically requires some type of framework or platform that can act as an intermediary between providers and consumers. Without this intermediary in place, consumers would have to build a more tightly coupled integration with a service endpoint. This intermediary could be implemented as a proxy, a gateway, or a broker, handling issues such as security, routing, SLA management, and life-cycle management.

The life-cycle management features offered by the platform are key to our discussion of versioning. Some Web services and SOA management platforms on the market today offer support for life-cycle management. This might include:

• The ability to handle multiple versions of a service at the same time
• Deprecating or retiring services in a graceful manner
• Routing requests to the appropriate service endpoint based on a request
• Transforming requests and responses to maintain backward compatibility (e.g., using XSLT)
• Automated deployment of new versions without requiring system shutdown
• Managing dependencies that exist between different Web services

Let's look at an example showing a common versioning problem. In Figure 4, a provider has offered an initial version of a Web service, V1.0. The platform would automatically route requests for this service to an appropriate service endpoint. Routing could be determined based on information placed in a UDDI registry, or the underlying management model could manage this (e.g., through WSDM interfaces).

At some point, a second version of the service is deployed that maintains backward compatibility. Within the SOA, the new service is identified as supporting both the original business service and the new business service. Requests made for the original business service could be brokered to either service endpoint. Consumers wishing to access the new functionality would have to make the appropriate programmatic changes.

This approach to versioning allows an IT organization to better adapt to changes required by the business. Multiple versions of a service can be maintained simultaneously without impact to the consumer. Old versions can be retired gracefully, and consumers can upgrade on their own time, rather than being forced to when new versions are released.

Deployment Considerations
Even with a solid design and robust architecture for versioning, there is still a human factor that must be considered in this process. Understanding the versioning life cycle will help you to implement new versions and deprecate the older versions effectively. The first step in this process is to put a solid plan together describing the life cycle of Web services being supported. This plan might include the following steps:
1.  Determine how often versions are to be released. When considering frequency, you should consider how many versions of the Web service you want to support in parallel.
2.  Understand the timeframe within which you expect consumers to move to a new version of a service. The Web services management platform may be able to provide guidance on service usage to determine the appropriate time to phase out older versions.
3.  Consider releasing a pilot or an early release of a new version. Give consumers an opportunity to test compatibility and determine potential code impacts.
4.  Approach Web services versioning the same way software packages might be released. Changes to your service, either as a result of bug fixes, partner requests, or specification upgrades, should follow a specific release cycle.
5.  Clearly communicate your Web services versioning strategy to users of your Web service.

Once the versioning strategy is laid out for each release you should then consider the following steps:
1.  After making the appropriate changes to your services, do unit and functional testing of the service.
2.  Deploy the new service through appropriate schema, WSDL, and service changes. This step might include registration to a UDDI registry or the Web services platform.
3.  Notify the consumers of your new service and pilot the new versions with one of your consumers.
4.  Run the new and old versions in parallel for the timeframe you have allocated in your versioning plan.
5.  Notify the consumers of your service of the date you expect to deprecate old versions.
6.  Remove old versions from WSDL descriptions and UDDI registries to prevent new consumers from discovering and using the older versions.
7.  Remove functionality of the old service, and add in appropriate functionality so existing consumers are properly notified (e.g., through a SOAP fault) that the old version is no longer supported.

One approach to deployment is shown in Figure 5. The calendar is shown in quarters of a company's financial calendar. The new version can be introduced at the beginning of a quarter (e.g., Q1 of 2003). It is valid for four quarters and then is sunset at the beginning of Q1 of 2004. In this case, the consumer of the service could be given six months to convert to the new version. You can also have minor versions released in between the major versions. These minor releases can then be folded into the Web service version 2.0 when it is released.

Conclusion
This article has presented a number of considerations when versioning Web services. Whether it's developing a versioning approach for schemas or building a full-scale versioning system using an SOA approach, there are a couple of key points that we would like to leave you with.

First, we hope it's obvious that versioning can become a nightmare as you deploy more and more versions of your service, especially if the service is being offered to different consumers. The goal of your design should be to build reusable components that can be leveraged and reused across the versions being managed. In the long run, this will reduce maintenance and deployment costs.

Second, don't underestimate the impact these changes might have on the consumer. While the design you introduce might reduce your development costs, you must also consider how these changes impact the end consumer. Service compatibility is key to this, and if new services maintain backward compatibility, consumers wishing to use the existing functionality shouldn't be required to change. The architecture should provide an easy migration and upgrade path for them.

Third, you want to strive to isolate the technical implementation and provide a clear separation between the consumer and provider. This might be implemented using design patterns such as the Facade, or it could require an SOA-based approach. Either way, the notion of coarse-grained business services offers a more loosely coupled architecture where consumers and providers can change without impacting the other party.

The last piece of advice we could offer is to not attempt to build the entire versioning infrastructure yourself. If you look at the requirements for manageability, they include a wide range of features such as routing, transformation, versioning, and security. Leveraging a vendor offering, especially one that provides a service-oriented approach IT management, can go a long way toward offering an architecture that can truly adapt to the changing needs of the business.

References