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
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)
That’s a good point. Major and minor version should be enough.
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?
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.
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.
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.
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.
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?
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.