Strategy for WSDL versioning?

["BLIS Webmaster (Patrick Houbaux)" <we...@blis-project.org>]

Hi all,

Does somebody has any good idea about the strategy to adopt for versioning an API exposed as a webservice?

My first idea is to add the version of the WSDL in the target namespace, something like:

urn:v1_0.myservice.mycompany.com

but there might be a nicer solution for that.

Can somebody provide any links to some documentations, discussions, etc ... about this topic?

Thanks.
Patrick.

Re: Strategy for WSDL versioning?

[Christopher Blunck <bl...@gst.com>]

There was an interesting talk at JavaOne (yes I'm ashamed I went) that talked
about this.  The proposed idea was to catalog your services in a UDDI registry.
Use dynamic binding to query to UDDI registry for endpoints.  Then, as part of
a self-imposed standard, define String getVersion() for each port.  

A client can float a query to UDDI saying "tell me the endpoints for this
interface".  UDDI will return N results.  As a client you can then call to
each of the N results and invoke getVersion().  Of the N, M will be a version
your client knows how to interact with.  Invoke the first endpoint in M.  If
it fails, invoke the next.  And so on and so forth...

Not a bad idea...



-c

On Tue, Oct 28, 2003 at 11:21:58PM +0200, BLIS Webmaster (Patrick Houbaux) wrote:
> Hi all,
> 
> Does somebody has any good idea about the strategy to adopt for versioning 
> an API exposed as a webservice?
> 
> My first idea is to add the version of the WSDL in the target namespace, 
> something like:
> 
> urn:v1_0.myservice.mycompany.com
> 
> but there might be a nicer solution for that.
> 
> Can somebody provide any links to some documentations, discussions, etc ... 
> about this topic?
> 
> Thanks.
> Patrick.

-- 
 17:35:00  up 1 day,  7:05, 11 users,  load average: 0.27, 0.13, 0.10

Re: Strategy for WSDL versioning?

["BLIS Webmaster (Patrick Houbaux)" <we...@blis-project.org>]

Thanks all for the information.

I have found some documentation about this subject on the web:
http://searchwebservices.techtarget.com/tip/1,289483,sid26_gci917380,00.html
http://internet.about.com/library/aa_webservices_031202.htm

According to this reading, seems that using target namespace for the version of the WSDL was not a good choice.

So the solution to the problem is not trivial, but it seems to be a convergence around the following solutions:
- getVersion exposed in the WSDL
- Different WSL exposed (one for each versions.
- Sending a message to users that the API has changed
- Using a service broker

Seems that I have some answers to my question here at least :)


Regards,
Patrick. 


 

Jeff Greif wrote:

> ----- Original Message ----- 
> From: "BLIS Webmaster (Patrick Houbaux)" <we...@blis-project.org>
> To: <ax...@ws.apache.org>
> Sent: Tuesday, October 28, 2003 1:21 PM
> Subject: Strategy for WSDL versioning?
> 
> 
> 
>>Hi all,
>>
>>Does somebody has any good idea about the strategy to adopt for versioning
> 
> an API exposed as a webservice?
> 
>>My first idea is to add the version of the WSDL in the target namespace,
> 
> something like:
> 
> 
> This is a super-unfriendly solution, since namespace change is a gratuitous
> incompatibility that basically breaks every existing client every time you
> change versions, even if that change is only to add new operations to your
> wsdl that didn't exist before, and thus have no effect on old clients.  You
> will not have happy users/customers if they incur a maintenance burden every
> time you upgrade versions.  Even if you're running the old version on a
> server somewhere also, so the old client doesn't break, if the user wants to
> upgrade he has to fix all the namespaces wherever they are used.  This would
> include not just the web service invocation code, but potentially schema
> location catalogs, code that uses XPath operations to rummage in the
> documents your service returns, code that queries databases of documents
> accumulated from the web service, XSLT stylesheets, etc.
> 
> A contrasting low-tech (but also not enterprise-production-quality) approach
> is to have a getVersion operation in your wsdl.  The user can put version
> checks in his client application to be able to use new features or handle
> incompatibilities introduced by version changes.  This will even allow a
> client to keep working if you have to turn off the latest version and revert
> to an older one.  Typically, users will do nothing to change their client
> programs when you change versions unless something breaks.  Then they'll put
> in suitable new version checks and conditionalized execution.  If their code
> doesn't happen to invoke the operations that change, they will not need to
> do anything.  Operating in this lazy customer maintenance model constrains
> what kind of changes you can make between versions -- anything that does not
> break old user code has to work exactly the same way, while
> incompatibilities must cause dramatic or at least readily noticeable
> failures.  The 'work exactly the same way' criterion is hard to maintain
> over successive version changes, and even harder to be sure about given the
> unforeseen ways users will invoke your service and manipulate the results.
> 
> This is a hard or at least highly non-trivial problem whose answer in any
> particular case involves a lot of tradeoffs.
> 
> Jeff
> 
> 
> 

Re: Strategy for WSDL versioning?

[Jeff Greif <jg...@alumni.princeton.edu>]

----- Original Message ----- 
From: "BLIS Webmaster (Patrick Houbaux)" <we...@blis-project.org>
To: <ax...@ws.apache.org>
Sent: Tuesday, October 28, 2003 1:21 PM
Subject: Strategy for WSDL versioning?


> Hi all,
>
> Does somebody has any good idea about the strategy to adopt for versioning
an API exposed as a webservice?
>
> My first idea is to add the version of the WSDL in the target namespace,
something like:
>

This is a super-unfriendly solution, since namespace change is a gratuitous
incompatibility that basically breaks every existing client every time you
change versions, even if that change is only to add new operations to your
wsdl that didn't exist before, and thus have no effect on old clients.  You
will not have happy users/customers if they incur a maintenance burden every
time you upgrade versions.  Even if you're running the old version on a
server somewhere also, so the old client doesn't break, if the user wants to
upgrade he has to fix all the namespaces wherever they are used.  This would
include not just the web service invocation code, but potentially schema
location catalogs, code that uses XPath operations to rummage in the
documents your service returns, code that queries databases of documents
accumulated from the web service, XSLT stylesheets, etc.

A contrasting low-tech (but also not enterprise-production-quality) approach
is to have a getVersion operation in your wsdl.  The user can put version
checks in his client application to be able to use new features or handle
incompatibilities introduced by version changes.  This will even allow a
client to keep working if you have to turn off the latest version and revert
to an older one.  Typically, users will do nothing to change their client
programs when you change versions unless something breaks.  Then they'll put
in suitable new version checks and conditionalized execution.  If their code
doesn't happen to invoke the operations that change, they will not need to
do anything.  Operating in this lazy customer maintenance model constrains
what kind of changes you can make between versions -- anything that does not
break old user code has to work exactly the same way, while
incompatibilities must cause dramatic or at least readily noticeable
failures.  The 'work exactly the same way' criterion is hard to maintain
over successive version changes, and even harder to be sure about given the
unforeseen ways users will invoke your service and manipulate the results.

This is a hard or at least highly non-trivial problem whose answer in any
particular case involves a lot of tradeoffs.

Jeff