Changing SOAP interfaces and deprecating web methods in java

Question

My team is developing a service layer in java and a GUI in dot-net, using soap. The GUI developers keep getting upset because the service layer occasionally change the web service interface.

To keep the GUI chaps happy, rather than trashing the original web methods we are now writing new ones that live alongside the existing ones. Since our soap interface design is still being refined this is getting messy, surely there is a better way! Any suggestions?

Further, there are times when we want to deprecate a web service method - is there a java annotation for doing this (one that would show up in the WSDL)?

Thanks for any suggestions

Answer 1

There is no such deprecation annotation that I know of. This is the general pattern that I normally use:

• Implement a SOAP api putting a version number (v1) in either the WSDL name or path
• Write new (or improved) app code that deserves an updated SOAP api
• Implement a completely new version of the SOAP api with a new version number (v2) beside the v1 code, but backed by the same domain classes
• Change the implementation of the v1 web service to perform migration and (whenever possible) call the appropriate method of the v2 service
• Notify clients that they should start using v2 instead of v1
• Wait
• If you're in a big enterprise environment, wait even longer ;-)
• Once nobody is using v1 any more (verify this with logs, and conversations with users), remove the v1 interface

This approach only works really well when you have good separation between your web service code and your actual application code. It helps to think of web service code as a presentation layer.