A short guide to API versioning

There is no clever trick in this one, just a handful of decisions worth making deliberately. Everything we would tell a client about API versioning in the time it takes to drink a coffee.

The right architecture for a team of three is the wrong one for a team of thirty, and vice versa. The practical test is whether someone new to the project could tell, in a minute, that it had been handled.

What is actually at stake

Version before anyone external depends on you, not after. In practice this is a scheduling problem more than a technical one. It rarely shows up as a line item, which is exactly why it slips.

How we handle it

Additive changes rarely need a new version. In practice this is a scheduling problem more than a technical one. Doing this properly once is usually cheaper than doing it approximately three times.

Warning signs

Publish a deprecation timeline and actually honour it. In practice this is a scheduling problem more than a technical one. Assume whoever inherits this will have half your context and none of your patience.

How to tell if yours is fine

Architecture is the set of decisions that are expensive to reverse, which is the only reason they deserve the name. Three things worth confirming about API versioning before you move on:

• Someone can say what the current setup is without going to look
• Version before anyone external depends on you, not after — and you know whether that is true here
• There is a way to tell whether the last change to this helped

Most of the value here comes from doing the first two things, not all of them.