How to handle the code for versioned SOAP web services?

Question

Background:

• our web services are company internal, but with a lot different systems using them
• we will strive to deprecate/remove old versions of the api as much as we can

There is a lot of information regarding versioning of web services, and our decision was to use the following approach to version our web services:

• Keep version in URL (I know some people are against this, but mainly in regards to REST services)
• Keep version in namespace.

But, now we are deciding how to actually implement this, and here we have not found that much information of best practices. We use (Java):

• Annotations to define our web services (and the web service api)
• POJO beans annotated with XML annotations, to define the content
• Converter classes to convert from/to the business layer and web service pojo’s
• Spring

So, to keep old versions on the web services, we need to keep old versions of the code. To do this, we have basically looked at two different approaches:

1) For each new version, make a complete new copy of the relevant code

This approach would look like this:

com.company.webservice.v3. -all of the web service classes, POJO’s and converters go here
com.company.webservice.v4. -all of the web service classes, POJO’s and converters go here

So, here we have the code duplicated. Our thought in short:

• Code duplication. Will be several classes with identical code. Perhaps confusing in Eclipse.
• Complete isolation, easy to determine what constitute a specific version
• Minimized risk to affect functionality of previous versions of the services

2) Use spring to only make a copy of each class that is affected by a change

This approach means that use Spring IoC and let all versions of the web services use, as much as possible, the same code. Only when we make a change that affect behavior/api, we make new versions of those classes. For example:

com.company.webservice.beans.MyXMLAnnotatedPOJOv3.java
com.company.webservice.beans.MyXMLAnnotatedPOJOv4.java
com.company.webservice.translators.MyXTranslatorv1.java
com.company.webservice.translators.MyXTranslatorv2.java

• Could be difficult to clearly see what constitutes a specific version of a web service. Maybe easier to by misstake affect previous versions of the web services when maintaining the code
• No code duplication. Only changes are implemented as new classes

Neither approach feels optimal, but we haven’t found much information regarding this. So, my questions is: which of the two approaches would you use? Or would you take a completely different approach?

Answer 1

When generating wsdls from Java, I would use the package solution:

com.company.webservice.v3.  

It has the code duplication problem, but the POJOs and converters have differences between versions anymay, so code reuse might not be very feasible after all. The main advantage is that if you want to get rid of an old version, you just delete the relevant packages.

I would keep versionnumber in URL, since you are not doing REST anyway. Furthermore, you could check in access logs, if certain versions are still used.