http://www.infoq.com/news/2013/12/api-versioning
Contract versioning and API/Service versioning has always been a consideration for SOA based systems. Whether because of the impact it has on composability, or client-service governance, it is still something of an art rather than a science. There are many examples of groups giving the benefit of their experiences (e.g., around REST is extremely popular). However, recently Jean-Jacques Dubray has written an article which attempts to inject some scientific objectivity into this problem domain.
I have been asked recently to create an estimate of the costs of versioning APIs (or Web Services). I wanted to share this estimate because I feel a lot of people still don’t understand the cost implications of API/Service versioning.
According to JJ, during the work they found that the cost of building APIs was dependent upon the approach used subsequently to version them.
The key point that [you need] to understand is that even if the cost to your consumers may look small to you, it is not just a pure cost, it is risks, disrupted project plans, unavailable budgets… with changes that often have no immediate business value to an existing consumer who was not expecting any change to API.
The article then goes on to classify three different approaches to API versioning (see the full article for a more in depth discussion of each, including how JJ defines a way to measure cost):
- The Knot. “All API consumers are tied to a single version of the API, when that API changes, all consumers have to change, in essence creating a massive ripple effect across the entire set of consumers / ecosystem.”
- Point-to-Point. “Every service version is left running in production and consumers are required to migrate on their own, when they need to. The maintenance costs increase as the number of version in production increases.”
- Compatible Versioning. “All clients talk to the same compatible API/Service version.”
Given these definitions and associated costs computed using the equations JJ describes, it is possible to plot the relative costs as shown below (y axis is cost, x axis is the version number):
As JJ says:
[…] a single version forcing every consumer to upgrade when the API changes is the most expensive to the ecosystem. A multiplicity of versions that need to be maintained is better, but still quite costly when you try to keep upgrading each version or alternatively operating older versions. A compatible versioning strategy seem to offer the best efficiency.
So what do others think? Is this way of calculating the cost of versioning APIs applicable beyond the environments in which it was developed by JJ and team? Does the relative cost explanation make sense given your own experiences? Are there other categories which JJ and team don’t cover?
