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.

We found in this study that the cost of building APIs can vary greatly based on the approach / pattern used to deliver subsequent versions of that API (or Web Service)

The key point 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.

When it comes to API versioning, I feel that there are three types of patterns that are relevant:

A) 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.


The cost of creating new versions of the service is best represented by that formula:



S = cost of building an API/Service

V = cost of building a version (update to API/Service)

U = cost of updating a group of API consumers

T = cost of testing each group of consumers works properly



B) 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.

The cost of creating new versions of the API/Service is best represented by that formula:


S = cost of building an API/Service (as an update to API/Service)

U = cost of updating a group of API consumer

T = cost of testing each consumer works properly

 There is also a hidden assumption in this formula which does not take into account the cost of operating more than one API version (which is not the case of Pattern 1 or 3). My assumption is that, U, the cost of updating a group of API consumer (which may not happen) represent the cost of operating a service, when it is not updated to catch up with newer versions. 

C) Compatible Versioning

 All clients talk to the same compatible API/Service version.


The cost of creating new versions of the API/Service is best represented by that formula:


S = cost of building an API/Service (as an update to the API/Service)

U = cost of updating a group of API consumers

C = cost of certifying that each group of API consumers will work properly

A = cost of preparing consumers and clients for compatible versioning 

Approximations & Assumptions

Let's do some approximations to be able to compare the relative cost of each pattern to the entire ecosystem (consumers and services).


The results seem to speak for themselves: 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. 

Of course in reality not every version can be compatible and an API with major (incompatible) version and (minor) compatible versions will be a combination of pattern 2 and 3. In any case, you should never put the consumers in the position to have to upgrade, unless this is a case of Force Majeure

In this figure, the Y axis represents the costs of creating API/Service versions, based on the approximations and assumptions stated above, the X axis is the version number of the API/Service (1..10).


User ratings
5 star:
4 star:
3 star:
2 star:
1 star:
1 rating
Average user rating:
5.0 stars
# IvanF on 12/04/13 at 08:06
5 stars

Brilliant summary and math for something I have had difficultly communicating in the past. Thank you.

# Mike Amundsen on 01/10/14 at 13:47

interesting post.

1) do you have a more formal “paper” style printing of this material that could be shared?

2) how did you arrive at your initial cost assumption values?

3) is there any historical tracking that bears out these figures?

4) have you applied this to more than one client/case and if so, what variances between model and actual did you find.

finally, in the Compatible Version example I think the “key” is missing a few descriptions (V & T).

# jdubray [Member]   on 01/15/14 at 23:33


thanks for your comment. I didn’t intended these calculations to be formal (I don’t think they can be). I just wanted to show that it is indeed possible to evaluate the implications of possible approaches in a given context.

Most people I talk to think at t = 0, they rarely look at the big picture over time. The goal of this short post was simply to encourage people to look beyond t = 0, using their numbers, their processes, …

V, T are the same as previous cases (versioning and testing)


# Owen Rubel   on 04/25/15 at 09:35

The reason this is such a high cost is because the api pattern is broken. The original api pattern as it was applied to the web was originally designed for localized architecture. But as it was applied to the web, it had to adapt to a distributed architecture. Unfortunately it couldn’t because the communication layer was TIGHTLY bound to the busines logic with thing like annotations (JAX) or RestFul Controllers.

Thus the data could not be shared with the other components like the proxy or MQ and it causes an architectural cross cutting concern. I have given talks on this at SpringOne, APIDays and had the API Manager at Netflix state about my work ‘this fixes everything we are currently having issues with’.

See https://www.youtube.com/watch?v=mZOs7oz0JOI

# jdubray [Member]   on 04/26/15 at 15:44


do you realize that the SOA guys have used that pattern for over a decade, it’s called an ESB, and in particular an ESB allows you to implement “compatible versioning".


The reason why people created an ESB is because some wise old men understood a long time ago that concrete classes, especially with annotations was not the right architecture. But what do I know?



I work at xgen.io

Recent projects

powered by b2evolution