Enterprise Integration Zone is brought to you in partnership with:

Rik has posted 3 posts at DZone. View Full User Profile

Top 10 SOA Pitfalls: #9 - Versioning

  • submit to reddit

Last week we started the Top 10 SOA Pitfalls countdown with #10: NIH syndrome. This week it's time for #9.

Version mismatch is one of the growing pains of a SOA. A SOA starts simple, but after a while new versions of services will appear and the complexity will grow. Good life cycle management and supporting tools will help you to control the complexity.

The implementation of a SOA will contain services. Initially the services are designed for a purpose. Consumers of these services will use the functionality as designed. However, over time the services might change or new functionality is needed. What effect will this have on the consumers, services and infrastructure?

Let’s take a closer look on these changes. The changes can be divided in major changes (v1.0 to v2.0 ) and minor changes (1.0 to 1.1). The following types of change can be identified (combinations of the types can occur):

  1. Minor change of interface: The current interface is extended without compromising the current functionality and interface usage. For instance adding a new method with new functionality.
  2. Minor change of functionality: The functionality is changed without effecting any consumers. The implementation is revised. For instance a bug fix of the current version.
  3. Major change of interface: The current interface is changed is such a way that it is not backwards compatible. For instance the methods are changed or the functionality is completely new.
  4. Major change of functionality: Although in this change the interface remains the same, the functionality is changed in such a way that it will affect the consumers.

In general the minor changes won’t effect the current consumers. These consumers can continue to use the existing interface or functionality. Normally the service can be replaced with the new version without keeping the old version online. Howver regression testing is desired in order to make sure that the new functionality/interface hasn’t affected the existing functionality/interface. Note that the new functionality should fit into the current SLA.

In a major change the changes will most likely effect the current consumers. The old version can’t be replaced by the new version for a couple of reasons.

  • The current consumers are not able to upgrade to the new version in time
  • The old functionality is still required, although it is not functional supported (only technically).
  • The consumers do not want to upgrade and/or are not willing to pay for the extra costs. These costs will raise in time in most cases.

In these cases two versions of the same service will be available for the consumers, although the functionality and interface differ. When multiple versions of a service exists, the complexity of the SOA increases. Although some companies will restrict the amount of versions in production it is often hard to maintain the versions. Often the functional support will only apply on the new version, but technically all versions should be supported. Maintenance is needed for both versions which could result in a minor new version for the old major version.

Versioning problems are in most cases caused by poor governance and lack of supporting tools. Practically the common problems with versions are:

  • Who is using the versions? Who used the old interface? How long ago did they use it?
  • Missing supporting tools to help manage the different versions.
  • How long is support needed for an old version. When is it save to upgrade or remove a version.
  • Are the consumers redirected to the right version?
  • Consumers are directly connecting to the services without a proxy.

In order to keep track of all these services a good registry is needed. The registry contains services that are active. The registry contains the location and the consumers that use the services.
Tools like an ESB can act like a proxy to different versions. The exact location of a version is hidden from the consumers. The ESB routes the call to the correct version of the service.

Note that generic public internet services are hard to version. In these cases the consumers are unknown and can’t be contacted. Although the same principles apply, the only way they can be notified is in an anonymous way (for instance a notification on a website).

In conclusion versions of services will change overtime. Therefore it is important to be prepared for these changes. Limit the amount of versions and keep track of who is using them in a registry. Use tools to hide the implementation from the consumers so you can be more flexible with multiple versions.

Next week, Viktor Grgic will move on to pitfall #8.

Reference: Top 10 SOA Pitfalls: #9 – Versioning at the Xebia Blog
Published at DZone with permission of its author, Rik de Groot.

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)


Alex(JAlexoid) ... replied on Tue, 2008/06/10 - 2:42am

SOA Versioning is not a pitfall it's a feature. And like with anything more advanced than a sponge, you can get into a lot of trouble.

But, really... Versioned services is a thing that is mostly overlooked, by most SOA pushing vendors. And ESBs can help, with modifying filters and routing policies. There is also alternative in creating SOA "enabling" application, at the center of it all.

Juan Pablo Royo replied on Tue, 2008/06/10 - 8:58am

I agree with Alex. SOA versioning is not a pitfall; it's part of this architectural style.

SOA’s nature become very complex when the amount of services start to increase, and as we know, the businesses change very fast too. The need of version a service become more real.

In this kind of scenario, we have to make decisions that govern the complexity of our SOA environment. One of this has to be with the strategies of versioning:

  • When should I have to version a service?
  • Should I have to version a service when some capabilities are added, when the Policies has to change, when the QoS has to become more restrictive or less one?
  • Should I have to version a service when the contract change? What is the contract then? What is the scope of it?
  • Should I version or extend the contract? Is It not the same?

I’ve tried to answer some of this questions from my SOA experience, and all the answers have brought me to same concept, “The Contract”. We can answer all this questions establishing when the contract is broken. If we consider the contract is broken when we are affecting the consumers (the capabilities change, the QoS change dramatically, etc.) we have to version the service, otherwise we can extend the service.

Per Olesen replied on Tue, 2008/06/10 - 9:14am

I am with Rik here. Services are fine, but you shall know, that one pays the price later in deployment scenarios with added complexity there.

Michael O'Keeffe replied on Wed, 2008/06/11 - 12:21pm

Rik, this is a good point. Given the "it's not a bug it's a feature" comments (I see their point too, including the humor), maybe the title could be revised to "Not correctly handling API versioning" or something similar?

Anyway, here's a good article on Best Practices for Web Services versioning

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.