Hi, Here is the humble experience of our team ; we have been exposing a bunch of web services for about two years :
* SOAP and REST services are versionned via ** the endpoint url : sample http://mycompany.com/services/UserProfileService/1.0/ ** the namespace of XML entities : sample http://mycompany.com/userprofile/v1_0/ ** SOAP action : sample http://mycompany.com/userprofile/v1_0/get * Even if many famous XML APIs (Amazon, Google, etc) use date versioning (e.g. 2009-04-03), we are happy with number versioning ( e.g. 2.3 ) because : ** it is easier to remember a number than a date. ** number versioning is self explanatory. We use minor version change when we add elements, enumerated values, etc ; we use major version change for data structure refactoring. Minor changes can most of the time be applied with simple package name renaming in the consumer code. * We versioned namespaces with "_" instead of "." because a while ago, CXF wsdl2java tool truncated the package name after the first point. Not sure it is still the case, we should have proposed a patch, shame on us :-) * We initially tried to have different version life cycles for sub schemas of our data structures (user v2.3 aggregates user.webprofile v1.0 + user.cellphoneprofile v1.6, etc) but it has not proven to be efficient for our reality because : ** we did not reuse a XSD for anything else than our web service (i.e. one XSD is used by exactly one WSDL) ** consumers were confused when they upgraded minor versions. We could not say "search and replace all the packages x.y.z.1_0 by x.y.z.1_1" ; instead, we had to say "change this package to ... and this package to and this other package to ..." :-( * We never used routing relying on "SOAP action" nor on "XML namespace" ; all the routing is done on the endpoint URL. * On the server side, we implemented service business logic versioning with : ** business logic located in the implementation of the latest version of the service ** java bean to java bean mapping to adapt to older versions of a given service ** mapping frameworks like Dozer have not proven to be useful, we now prefer hand coded mapping ( 'userV13.setLastName(userV21.getLastName()) ...' ). * We failed to remove old versions of the services, our consumers did not upgrade. It causes a bit more work on the provider side but less on the consumer side. Even if some will say SOA heresy, is it that bad ? Consumers are quite happy with it :-) * OK, we admit it, we don't know who are our consumers, especially for REST services authenticated by internet users credentials. Still a SOA heresy but still the sign that some consumers feel our services are useful :-) * We use per operation and per version JMX monitoring. It tells us prehistoric versions are still very famous :-) * According to Hyperic HQ, we have 8.000 requests per minute and per server on our web WS application without major issues ; bean to bean mapping processing is very cheap, we never see it when we generate thread dump with the great jstack tool. * URL based versioning helps to get monitoring and audit with simple greps on access logs. We hope this feedback helps, Michael and Cyrille -- Michael Figuière mfigui...@xebia.fr Cyrille Le Clerc clecl...@xebia.fr On Mon, Dec 14, 2009 at 12:41 PM, Sergey Beryozkin <sbery...@progress.com> wrote: > > Hi, > > Apologies for a late reply, I was planning to reply for a while :-) > As far as approaches toward versioning SOAP services are concerned, see [1] > which Oliver also referenced in the other email and which is being used in > production and also check [2] for some general information. > [3] captures some good advice on how to deal with versioing restful services, > some of it may apply to SOAP services too. > > It is also may make sense to explicitly require or at least recommend the > consumers to ignore unrecognized tags, provided that the breaking change is > signalled by a namespace change. It may let you avoid the 'noise' (frequent > namespace change) when the schemas get updated with the tags which don't > affect the existing consumers, example, an element called "book" has a new > element "category" added which should not affect the consumers knowing about > the book/name only. This is called a forward compatibility. See Versioning in > [4] for example (though Web3s is defunct now at least publicly). > > Likewise, a service provider should typically ensure a backward > compatibility, that is newer services should continue accept the requests > from older clients. > > For the same reason (that is, to avoid the 'noise' but at the code level), > I'd recommend just to have a single complex type in every resource method > signature on input/output. If the policy is to ensure the code gets changed > even with a minor update then you can 'enforce' the failure at runtime by > enabling the strict schema validation. > > It much depends on what exactly you would like to achieve. In the end of the > day you can always count on CXF :-) in that it offers a numebr of options for > having a single class servicing multiple clients, see [5] for some info. > Example, you can use XML stream readers/writers for both JAXRS and JAXRS > services and utilize multiple jaxws: and jaxrs: endpoints referncing the same > bean but using different readers/writers or filters or (jaxb) provider > instances, etc > > hope it helps, Sergey > > [1] http://blogs.iona.com/sos/20070410-WSDL-Versioning-Best-Practise.pdf > [2] http://www.w3.org/TR/2007/REC-wsdl20-primer-20070626/#adv-versioning > [3] > http://www.25hoursaday.com/weblog/2007/05/08/RESTWebPlatformsAndVersioning.aspx > [4] http://dev.live.com/livedata/web3s.htm#_Toc165288982 > [5] > http://cwiki.apache.org/CXF20DOC/jax-rs.html#JAX-RS-CustomizingJAXBXMLandJSONinputandoutput > > ----- Original Message ----- From: "Pydipati, Karuna" <kpydip...@stubhub.com> > To: <users@cxf.apache.org> > Sent: Thursday, December 03, 2009 6:56 PM > Subject: Versioning of web services? > > > Is there any good strategies out there to do versioning of web services? > Does CXF recommends/supports any such versioning strategies? Is there > any difference in versioning between REST versus SOAP services? Also, if > I am doing a *dual* publishing (publishing SOAP and REST from same > interface methods), how to achieve versioning of SOAP/REST concurrently? > Any documentation on CXF site? Thanks in advance. > > > Regards > > Karuna Pydipati > > StubHub/eBay - Platform & Services > > Phone: (415)222-8752 > > Email: kpydip...@ebay.com <mailto:kpydip...@ebay.com> > > > > >
