Hi Brice- The versioning discussion is something that I've been trying to put together a solid solution to for some time. I figured I'd chime in to discuss what my current solution is for both an opportunity to share some ideas and accept some critique in an effort to improve my overall design.
The response is long, however, I'm hoping that the response is enough of what you are looking for to justify the length. Much like you’ve found, my SOAP solution for versioning is rather heavyweight. I’ve tried to do a couple of things to allow the RESTful versioning to fit nicely but I haven’t really crossed that bridge yet. For a particular service, let’s just use addressbook as an example, I have the following package structure: com.acme.services.addressbook.v1.soap com.acme.services.addressbook.v1.types Each package contains a package-info.java file, which set the namespace to something along the lines of: http://www.acme.com/api/addressbook/v1. We version at the package and namespace level, as well as, the JAR level when the API code is packaged up (i.e. address-book-api-1.0.0.jar). The service endpoint interface and implementation should both reside in the com.acme.services.addressbook.v1.soap package. However, from a JAR packaging perspective, they aren’t necessarily packaged together. The service endpoint interface is packaged in an API specific JAR, while the service endpoint implementation is kept with the other server code (more on this later). All message/data transfer objects sent to and from the server, as part of the service API, reside in the com.acme.services.addressbook.v1.types package. This was done so that we could, potentially, reuse these types for RESTful services i.e. register Jackson to de/serialize our JAXB beans into JSON. But I actually haven’t fully tested this, but based off CXF documentation and other replies in the mailing list I believe this to be possible. New methods and new complex types can be added to the v1 interface and implementation so long as they are backwards compatible. When you reach a point where you have a non-backwards compatible change you have to create version 2. In this case we would create the additional packages/namespaces/jar files to support this new interface and would make the appropriate changes there. One interesting point here would be that the API files would again be packaged separately than all other implementation and API code i.e. address-book-api-2.0.0.jar. This jar would not contain any v1 code. As I mentioned above we also version at the JAR level as well. This has an impact on deployment. There are two artifacts that result from a build and both should be versioned independently. The first artifact is the actual API jar file. The contents of this file should contain the service endpoint interface and all files from the com.acme.service.addressbook.v1.types package. As mentioned this should have it’s own versioning value, the reason for this is that the change frequency on the API itself should be different from the implementation versioning. In other words, the API shouldn’t change as much as the implementation. The second artifact is the actual WAR file. This artifact should contain the service endpoint implementation, along with all of the critical business logic and domain objects. As stated above this artifact should also have it’s own versioning. The idea of having it’s own versioning is that you might make changes (bugfixes, spring 2 to spring 3) to the implementation that have no impact on the API itself. Figure it more of an internal version number because the key version is which version of the API does the server support. For instances where you have a v2 that needs to be supported you would bring in both v1 and v2 of the JARs as dependencies of the service and would support both versions of the interface until any development/business agreements allowed for the removal of the v1 interface. What about REST? Truth be told we have no RESTful services at this moment. However, I believe it’s reasonable to assume that in the near future this fact is going to change (look at API trends and you’ll see what I mean). Therefore, I’ve put some thought into what we are going to do in this situation. It’s untested so use at your own risk. The theory goes that you would have an additional package: com.acme.services.addressbook.v1.rest The idea here would be that the appropriate Controller (I think that’s right term) objects would be defined here. Now in both cases, SOAP and RESTful web services, both the service endpoint’s and controllers serve as delegators back to the appropriate business logic component. Therefore, the endpoint implementation (in the SOAP case) is responsible for mapping to/from data transfer object into domain object and then delegating to business service component to carry out the actual business logic. This allows “potential” reuse between RESTful and SOAP based web services interface. Other solutions that I considered were doing some sort of message translator pattern that would add/remove values to messages based off the message version. However, I’ve had some experience using that style for other projects that I worked on. I always felt that it was the wrong choice for that previous project and that bad taste has carried over. So it’s more a personal bias rather than invalidation of the strategy itself. There are obviously a bunch of details in here that I can try to elaborate if you have any questions. But I hope this helps and not confuses. Derek Here is additional version resources that I've found to be helpful to me: - http://blogs.iona.com/sos/20070410-WSDL-Versioning-Best-Practise.pdf WSDL Versioning Best Practise - http://www.infoq.com/resource/articles/Web-Service-Contracts/en/resources/ERL_WSContractVersioning_013613517X_20-22.pdf Web Service Contract Design and Versioning for SOA (Chapters 20-22) - http://www.infosys.com/consulting/soa-services/white-papers/Documents/service-versioning-SOA-1.pdf Service Versioning in SOA - Part I: Issues in and approaches to Versioning - http://www.infosys.com/consulting/soa-services/white-papers/Documents/service-versioning-SOA-2.pdf Service Versioning in SOA - Part II: Handling the impact of Versioning - http://www.activevos.com/content/architects/getting_started/versioningschemasandwsdlsbp.pdf Versioning Schemas and WSDLs - Best Practices - http://wso2.org/library/whitepapers/2011/10/practical-soa-solution-architect Practical SOA for the Solution Architect (requires reg) - http://developer.ebay.com/DevZone/XML/docs/HowTo/eBayWS/eBaySchemaVersioning.html Schema Versioning Strategy (eBay) - http://www.infoq.com/articles/contract-versioning-comp2 Contract Versioning, Compatibility and Composability - http://www.xml.com/lpt/a/1492 Extensibility, XML Vocabularies, and XML Schema - http://developers.sun.com/jsenterprise/archive/nb_enterprise_pack/reference/techart/design_patterns.html Introducing Design Patterns in XML Schemas -- View this message in context: http://cxf.547215.n5.nabble.com/Open-question-about-versionning-tp5095403p5132084.html Sent from the cxf-user mailing list archive at Nabble.com.
