Why web services versioning is important

Freshness Warning
This blog post is over 17 years old. It's possible that the information you read below isn't current and the links no longer work.

17 Feb 2006

Two words: client synchronization.

Talking to Bill Lazar, he suggested that my web serrvices versioning problems are similar to his problems with Ruby on Rails. He’s got some code running on a pre-1.0 RoR installation. With 1.0, several important constructs changed in the framework, and upgrading to 1.0 would break his application. As we chatted through this, we hit upon the key difference. Although RoR released 1.0, there’s nothing forcing him to actually use it. He can keep using 0.9 (or whatever version he has) as long as he wants. He can try his code on a 1.0 system elsewhere, test it, adjust it, and prepare it for use. Then when he’s ready, he can upgrade his code and his RoR installation at the same time. The version negotiation between the client and server can be planned and synchronized.

For a data structure or service delivered over the public web to a disparate set of clients, this isn’t possible. I cannont time the upgrade of the server to co-incide with an upgrade of the client. In many cases, I don’t even know who the client is. I certainly don’t control them. And even if I knew them all, synchronizing an upgrade would require that I coordinate the upgrade schedules of multiple clients, maintained by multiple people, with varying degrees of interest and need.

The essential component in Bill’s Rails upgrade is a time shift. The RoR framework was released, but Bill can choose when it applies to him by shifting the upgrade to a time that suits him. People that need it now, or are just starting out with Rails can get the 1.0 version immedately. Everyone else can use whatever version they want. The Rails team doesn’t need to maintain old versions of the application. It’s acceptable to say that bugs in the app are fixed in the later versions only and if you have a problem that needs fixing, you should accelerate your upgrade schedule.

With a web service, I can time shift the upgrade path by continuing to supply older versions of the data format. There’s no maintenance involved. The format sits there, and anyone connecting to it can use it. If someone has a problem or needs some new data, they can get it by moving to the newest version. Any new uses of the service start out with the latest version.

Recently Written

The Trap of The Sales-Led Product (Dec 10): It’s not a winning way to build a product company.
The Hidden Cost of Custom Customer Features (Dec 7): One-off features will cost you more than you think and make your customers unhappy.
Domain expertise in Product Management (Nov 16): When you're hiring software product managers, hire for product management skills. Looking for domain experts will reduce the pool of people you can hire and might just be worse for your product.
Strategy Means Saying No (Oct 27): An oft-overlooked aspect of strategy is to define what you are not doing. There are lots of adjacent problems you can attack. Strategy means defining which ones you will ignore.
Understanding vision, strategy, and execution (Oct 24): Vision is what you're trying to do. Strategy is broad strokes on how you'll get there. Execution is the tasks you complete to complete the strategy.
How to advance your Product Market Fit KPI (Oct 21): Finding the gaps in your product that will unlock the next round of growth.
Developer Relations as Developer Success (Oct 19): Outreach, marketing, and developer evangelism are a part of Developer Relations. But the companies that are most successful with developers spend most of their time on something else.
Developer Experience Principle 6: Easy to Maintain (Oct 17): Keeping your product Easy to Maintain will improve the lives of your team and your customers. It will help keep your docs up to date. Your SDKs and APIs will be released in sync. Your tooling and overall experience will shine.