You are viewing a plain text version of this content. The canonical link for it is here.
Posted to users@cxf.apache.org by "Pydipati, Karuna" <kp...@stubhub.com> on 2009/12/03 19:56:00 UTC
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: kpydipati@ebay.com <ma...@ebay.com>
Re: Versioning of web services?
Posted by Cyrille Le Clerc <cy...@cyrilleleclerc.com>.
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 mfiguiere@xebia.fr
Cyrille Le Clerc cleclerc@xebia.fr
On Mon, Dec 14, 2009 at 12:41 PM, Sergey Beryozkin
<sb...@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" <kp...@stubhub.com>
> To: <us...@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: kpydipati@ebay.com <ma...@ebay.com>
>
>
>
>
>
Re: Versioning of web services?
Posted by Sergey Beryozkin <sb...@progress.com>.
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" <kp...@stubhub.com>
To: <us...@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: kpydipati@ebay.com <ma...@ebay.com>