My blog has moved and can now be found at

No action is needed on your part if you are already subscribed to this blog via e-mail or its syndication feed.

Wednesday, April 4, 2007
« Concurrent Computing, SOA and Performanc... | Main | Java Tutorial for Web Service Interopera... »

I had the opportunity today to give a presentation on SOA and its relationship to Net-Centricity to various folks in my organization. During the Q&A session that followed the briefing, there was a question regarding service versioning.

Just to provide some context, in my briefing one of the items that I touched on is the concept of Loose Coupling and how that enables the abstraction of interface from implementation and gives a service provider the ability to change out their implementation without affecting the service consumer.

To paraphrase the question "I have a service that is being used by multiple parties, and I am changing the implementation of that service but not the interface. (1) From a testing and certification perspective, what should I do? (2) What mechanisms exist to communicate this change to all the folks who are using my service?"

The interesting variation that this particular question posed was that changing out the implementation in this example was NOT about changing implementation technology but changing the processing algorithms/business logic associated with the implementation.

My answer to (1) was that if the algorithm/business logic change had the effect of changing the expected result (as compared to the original implementation), at that point I would consider this implementation to be a whole new service and would consciously break the interface. For example, in the case of a web service implementation, I would change/update the namespace of the schema such the it would break compatibility with existing service consumers. I would also have to have this service be tested and certified as though it was a new service.

But before I do that, I would have to notify the consumers that are using my service that I am about to make this change. Which relates to my answer to (2). AFAIK, at present there is no standardized, automated way of notifying all existing service consumers that I am about to change out my implementation. So in the current state of technology, what I would have to do would be to set up a mechanism/process as part of the original client provisioning on how I as a service provider would communicate changes and updates of importance to my service consumers.

The example I pointed to was how Google implements its AdWords API versioning strategy:

The AdWords API supports multiple recent versions of the WSDL to allow developers time to migrate to the most recent version. Once an earlier version of the WSDL has been replaced by an updated version, the older version will be supported for four months after the launch of the newer version.

During this period, the AdWords API will continue to provide developer access to and documentation support for any version dating back two months.

You can tell which version of the WSDL you are accessing based on the access URL namespace, which includes the version number. Versions are named with the letter 'v' followed by whole numbers (v5, v6, etc.).

The Release Notes summarizes changes between versions. In addition, new versions and shutdowns of older version are announced via the AdWords API Blog.

In addition to this documentation, whenever we release a new version of the AdWords API, new versions and older version shutdowns will be announced via the AdWords API Blog.

In the above example, the communication mechanism is the AdWords API Blog and it is incumbent upon service consumers to subscribe to it to keep updated on what is going on with the API. And Google provides a 4 month window in which they run both the old version and the new version side-by-side to give you time to move from one to the other.

But I have to admit that this is a situation that I have not personally run into (change in implementation logic, no change in interface), so I am basing my answers on various community best practices and conversations with folks who have had to do this.  If you have run into this particular situation before, I would be very interested in knowing how you handle this in your organization, especially any info you can share on the governance policies and processes that you have put into place to communicate upcoming changes.

4/4/2007 10:39 PM Eastern Daylight Time  |  Comments [4]  |  Disclaimer  |  Permalink   
Thursday, April 12, 2007 4:12:25 PM (Eastern Daylight Time, UTC-04:00)
I personally think the AdWords policy is quite terrible. They are changing the interface, and that inconveniences untold numbers of customers. It really surprises me that they'd do this and (seemingly) get away with it.

Their problem, as with most "Web services", is that their interfaces are too implementation-specific and therefore if the implementation changes the interface does too. What's needed is an application-neutral interface such as the one offered by the Web. On the Web, "change in implementation logic, no change in interface" is pervasive and so obviously massively successful. People just don't think of it in those terms though. *shrug*
Thursday, April 12, 2007 8:50:32 PM (Eastern Daylight Time, UTC-04:00)
>On the Web, "change in implementation logic, no change in interface" is pervasive

Yes it is. But a by product of that is that you have issues of Trust when results change without an understanding/notification of why that change occurred.

Say that you have an application-neutral interface and that the implementation behind it does change. Is it not incumbent upon you to notify your users that the way that your application is processing information, and the results that are provided as a result of that processing change are different from what they were originally lead to believe? If you do not notify them, it almost seems to become the web version of bait-n-switch. So, even in this case, would you still need to have some sort of a consistent way of notification?

I most certainly would not argue with the fact that versioning is definitely one of the elephants in the room with regards to web services and there has not been enough work done in this area to make it as smooth as it could be. So, if we are using SOAP based services, we work with what we got. Not ideal, not pretty (in point of fact, pretty ugly), but it is an approach.
Anil John
Tuesday, April 24, 2007 11:45:30 AM (Eastern Daylight Time, UTC-04:00)

Getting back to your original question, I place the burden on the service provider to ensure that notifications go out, and I think they should leverage whatever tools they have at their disposal. Clearly, tools should provide support in this, such as providing RSS feeds for individual serivces in the registry/repository, the ability to register an email address for more push-style notifications, web-based discussions for individual services, wikis, blogs, etc. That being said, it's the responsibility of the service provider to ensure that this communication is bi-directional. If they rely on a blog or an RSS feed to do a one-way push, they run the risk of clients not paying attention to it. There's only so much that can be done, but in the end, the service provider must be consumer focused, providing excellent customer service. To this end, the notification must set expectations for the consumer. Notifications, in my opinion, should go out for any change. If the implementation changes but the interface doesn't, you could still have new performance characteristics that can impact the end-user experience of a consumer. If the interface needs to change, guidance should be provided on what consumers will need to do to their end of things. Is it a major structural change that may take weeks, or is it a simple change that may only require regression testing? Will some mediator in the middle be leveraged to maintain backward compatibility for some period of time? Again, the easier the provider can make it for the consumer to remain compliant, the better.

Wednesday, April 25, 2007 9:28:06 PM (Eastern Daylight Time, UTC-04:00)
Thanks Todd! While I agree that the burden is on the Provider to enable notifications and to provide mechanisms which align with how the Consumer is able to get information, my only comment to add would be that there is a shared responsibility on the part of the Consumer to avail themselves of the mechanisms as well.. i.e. They can't just sit back and start sniping the producer about the upcoming change. I would think that how versioning, change management etc. are handled, would be things that would have to be worked out as part of the client provisioning phase as well.
Anil John
Comments are closed.