[Web] Service Versioning Guidance

Oh man, I have waited years to be able to post this blog entry. I am finally in a position to release real pragmatic guidance on how to version your services based on your particular scenario. Just last week we kicked off a project that is part of a much larger effort (no, I haven't blogged about the big project yet) that addresses versioning services. If you know me or have followed my blog, you'll know that I'm pretty passionate about this problem. No, I don't have all the answers just yet, but at least I have more time, resources and money (WooHoo!) to throw at the problem :)

The first thing we're doing is putting together a rough positioning paper on what we think the problem space looks like. It also defines all of the areas in a solution that can be impacted by a (good or bad) versioning strategy. Lastly, we're going to define some scenarios that break this space up. I've thought for quite some time that the only way to provide comprehensive versioning guidance is to break it up into scenarios and tackle each one ... divide and conquer!

The whole goal of a versioning strategy is to make life less difficult for certain people. These are some of the most prominant people involved:

  • The developer of the client
  • The operations (management) team
  • The deployment team
  • The developer of the service

Naturally, we would want it to make life easier for everyone, but the way I see it, if we have to add a little complexity for the service developers to make life easier for everyone else ... so be it. They're supposed to be smart people, right :) I do feel pretty strongly that the client should have to do as little as necessary to support the versioning of the service. Fortunately, life might already be okay for some of these people ... it depends on the scenarios.

The way I see these scenarios breaking down at the most fundamental level is based on the relationship between the service and its consumers. Known consumers mean the service knows about the consumers. These consumers can be broken down further into the ones under control by operations and those that aren't. In other words, if the IT department decides to version a service, are they in a position to push down new consumers (through SMS, ClickOnce or some other approach). The IT department knows about the not controlled group - they just don't have a way of deploying new versions of them. They might, however, have a means in place to contact them, or send them notifications. The unknown consumers are like the lost cause and while this may sound hopeless, in my experience and research, this is a very rare scenario outside of playground or testing Web services like xmethods.com. We're considering making this out of scope for the guidance. Let me know if you don't want me to do this - and why.

The vertical boxes may exist for known and unknown consumers. Validation means there is a requirement to perform XML Schema validation on the messages to and/or from the service, and extensibility means the message must support extensions. This different (but related) to versioning. I'm calling these things out because the guidance may change when these requirements exist.

Message format is referring to SOAP, binary, or some other format the message will take while on the wire. In all honesty, I'm not yet sure if this is going to impact the guidance or not ... so I'll include it until I can dismiss it. Because of course the guidance should be appropriate for all services ... not just Web services. And lastely, there is a good possibility the guidance will differ when versioning old services (that were deployed without a versioning strategy) versus new services that have planned for evolution.

Okay, that's enough for now. If you're interested in this stuff and have the time to review guidance, let me know and we'll see what we can do about involving you in this project. I'm really interested those of you have have real challenges you're trying to address - I'm doing this for you - so drop me a note. I'm posting this to get feedback, so if you have thoughts on this stuff, leave a comment.