CodeBetter.Com
CodeBetter.Com
RSS 2.0 via Feedburner
           Do you Twitter? Follow us @CodeBetter

Jeffrey Palermo (.com)

Blog moved to www.jeffreypalermo.com

Web service versioning for dummies - level 200

This post is aimed at providing a good way to version web services.  Note that there are many ways to do this, and this is just one way.

When versioning a service, it's important to be able to run multiple versions side by side.  When you upgrade the web service for one client, you can't immediately take away the current version from existing clients.  Existing clients will move to the new version if/when they can/want to.

The identifier for the web service is the Url, so the version number must be embedded in the url.

Here is one way to do it:
https://theServer/v1_0/theService.asmx
When you want to modify the web service, do so, but deploy it side-by-side with the current version:
https://theServer/v1_5/theService.asmx

With this versioning strategy, you will be able to publish upgraded web services while maintaining service to existing customers.  Down the road, when you have confirmed that all customers of the v1.0 service have moved to the v1.5 service, you can discontinue the v1.0 version.

I've learned that if there are urls with dots (.) in the path, then the IIS lockdown tool won't work with them.  For that reason, it's probably good to use (_) instead of (.) for the version delimiter.  I also agree with the first commenter that major and minor versions are enough.

There are plenty of folks talking about web service versioning:
http://www-128.ibm.com/developerworks/webservices/library/ws-version/
http://www.webservicesarchitect.com/content/articles/irani04.asp


Comments

Eber Irigoyen said:

not bad, I would prefer something like

http://theserver/theService/v1.0/theservice.asmx
http://theserver/theService/v1.5/theservice.asmx

4 digits for an official version seems like very *unstable*, probably 4 digits for your internal testing, and if that's the case, you shouldn't need side by side versions that often (that's why you're still testing)
# March 22, 2006 12:46 AM

Jeffrey Palermo said:

That's a good point.  Major and minor version should be enough.
# March 22, 2006 10:18 AM

Gary Williams said:

Is there a nice way of pointing a web service from one version to the next?  That is can you promote people to the new code base under the covers?  Is there a generic way of accomplishing this?
# March 22, 2006 11:05 AM

Jeffrey Palermo said:

You can publish a web service url that is considered "always the latest version".  Then people who use that will always be upgraded.

If you are in a situation where you want the v1.0 version to redirect to v1.5, then you can easily to a url rewrite, and the web service call can be fulfilled by the v1.5 web service even though the client was pointed at v1.0.
# March 22, 2006 6:01 PM

darrell said:

I'd always gone with the idea that the version number should either be part of the xml passed in, or that you could reverse engineer the version based on the xml schema passed in.  The explicit nature of your scheme has its benefits.
# March 22, 2006 9:46 PM

Brendan said:

Jeff, I've always thought that the OBP (one big paramater) approach works well for versioning services. This way you can deprecate add or change your request message schema, without breaking clients.. I avoid primitive type paramaters in services like the plague.
# March 23, 2006 9:40 AM

Jeffrey Palermo said:

The version of a service is part of the locating information.  Same as GACed .Net objects.  You do a hard reference to the version of the library.

I stay away from big blob service parameters like the plague. :)  I stick with primitive type parameters.  It's one Xml string going over the wire anyway.  Compatibility is determined by policy, so if I have a need to interoperate with non-.Net systems. we'll test for that, but I don't make my services uber-interoperable by default - that just takes time that's not accounted for in ROI.
# March 23, 2006 12:18 PM

Eber Irigoyen said:

now if you are worried about "breaking" current clients using your web service, you only need to worry if you are changing names/signatures of current functions right?

so if you ONLY add new functions (or modify code inside one of the current, without changing signature) and your clients point to the new version, they will still be ok right?
# March 23, 2006 5:16 PM

Jeffrey Palermo said:

Breaking current clients is an obvious concern.  Upgrading services while keeping the interface constant was tried with COM+, and it failed miserably.  A service could be proclaimed to be backwards compatible, but without complete testing, we don't know for sure.

Any time a service is changed (even internally), all clients must retest to ensure the complete systems still work.

My team is using a 3rd party web service, and we will not allow them to upgrade the web service without our knowledge because ANY change to that web service MIGHT mean downtime for our system, and that's not acceptable.  We've tested with v1.0, and there is no benefit for us moving to their v1.5.  It's a benefit for them, but not us, so we prefer not to accept the risk or testing cycle to upgrade.  We're happy with v1.0, and we'll stay with it.  The vender can continue with v1.5 while we remain on v1.0.
# March 23, 2006 6:03 PM

About Jeffrey Palermo

Jeffrey Palermo is a software management consultant and the CTO of Headspring Systems in Austin, TX. Jeffrey specializes in Agile coaching and helps companies double the productivity of software teams. Jeffrey is an MCSD.Net , Microsoft MVP, Certified Scrummaster, Austin .Net User Group leader, AgileAustin board member, INETA speaker, INETA Membership Mentor, Christian, husband, father, motorcyclist, Eagle Scout, U.S. Army Veteran, and Texas A&M University graduate. Check out Devlicio.us!

This Blog

Syndication

News

Headspring Systems

View Jeffrey Palermo's profile on LinkedIn

See my new blog at .jeffreypalermo.com