Web Services Life Cycle: Retirement

With respect to versioning, the Web services life cycle includes many stages: all but one of which has been discussed so far. (The last stage we discussed was Web services change -- the process of upgrading consumers to the new version of a Web service.) Now it's time to describe the process of retiring the old version -- Version 1 in previous examples -- of our service.

Web Services Life Cycle: Removing the Old Service Interface

Obviously, the old interface to (what is now) the Version 2 Web service should not be kept forever. If Version One is significantly different from Version Two, then we've probably engaged in namespace versioning up front -- or some other tactic; in any case, at some point in time, it will be imperative to rid the network of that old interface to the service. There are then two questions which must be answered in order to move forward:

• Who used the old interface?
• How long ago did they use it?

Often it's very difficult to tell whether: a) a consumer hasn't used an interface recently or b) a consumer is no longer using the interface, period. Looking at historical usage information, it may be possible to see that x number of consumers are now actually using the Version Two interface -- so it's clear that they've upgraded -- but it will still be important to tread lightly in the case of those consumers who have (apparently) done nothing by way of using Version Two. It may simply be unclear as to whether these consumers have actually used the new version of the service. It will be essential in this type of scenario not to rid the network of older interfaces to the service. Instead, simply disable these older interfaces. Repeat: don't discard them; disable them. In this way, the interface to the service will remain, but now it will return errors to the consumer.

After a certain point in time, then (if the old interface is disabled but not discarded), the Version One interface of the service will return an error to the consumer that says something like "you must upgrade to Version Two". Had the interface been totally discarded instead, the errors people would have gotten back would have been meaningless: consumers would have seen errors like "service does not exist". These kinds of errors are by default "mysterious" to the consumer -- and fail to help them accomplish their tasks. Bottom line, such errors leave consumers in the lurch. But if, instead, the user is given the opportunity to use the old (disabled) interface and then receives an error message that says, in effect, "please migrate over to such-and-such a URL featuring Version Two of the service", the user's sense of mystery will be more rapidly dispersed -- and she will be able to get on with the task at hand. Problem solved.

Web Services Life Cycle: Phased Decommissioning

In most cases, therefore, a phased decommissioning of the old interface will be required. The first stage, once it seems relatively clear no one is using the old version of the service, involves disabling the interface as described above. The interface should then be left disabled for "a long time": to make certain anyone else who subsequently uses it receives a meaningful, helpful error message. Only in the end -- perhaps after weeks, months (or even years) -- should the interface be discarded. But this process of actually discarding the old interface can very often prove painful -- particularly when applications have been coded to maintain a bunch of versions of the same interface for the same service: multiple interfaces for the same service. Those who have worked with Microsoft COM are well aware of this sort of pain.

Web Services Life Cycle Summary: Tools to Make Life Easier

In the Web services world, decommissioning service interfaces is actually much easier because tools like the Web service management intermediary make it simple to maintain many versions, many different interfaces for a service, without having to code all that detail into the service. A Web service management intermediary can solve a lot of these challenges -- and obviate the need to hand-code interface versions into services. That process consumes valuable time; the point is, there are now SOA tools to help solve a lot of these problems.

For More Information

Find out everything you need to know about versioning -- in the context of the entire Web services life cycle: download the free webinar, SOA Versioning Made Simple