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:

 

where:

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:

where:

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:

where:

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

Results

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

3 comments

User ratings
5 star:
 
(1)
4 star:
 
(0)
3 star:
 
(0)
2 star:
 
(0)
1 star:
 
(0)
1 rating
Average user rating:
5.0 stars
(5.0)
# 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

Mike,

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)

JJ-

Search

 Subscribe







powered by b2evolution