API versioning, explained without the jargon

It comes up on almost every project, usually later than it should. Here is API versioning without the vocabulary that usually surrounds it.

The right architecture for a team of three is the wrong one for a team of thirty, and vice versa. The teams that stay on top of it are the ones who put it on a calendar rather than a wish list.

The short version

Version before anyone external depends on you, not after. There is a version of this that is over-engineered, and it is worth avoiding. Anything you cannot measure here, you are deciding by taste, which is fine as long as everyone knows it.

Why people complicate it

Most of the confusion comes from tooling rather than from the idea itself. The cost of getting this wrong is rarely visible on the day it happens.

Additive changes rarely need a new version. The teams that handle this well are rarely the ones with the biggest budgets. Assume whoever inherits this will have half your context and none of your patience.

Turning this into a decision

Publish a deprecation timeline and actually honour it. The cost of getting this wrong is rarely visible on the day it happens. It is the sort of thing that looks like polish right up until it costs you an enquiry.

In practice

Most systems fail at the seams rather than inside any one component. Three things worth confirming about API versioning before you move on:

• Someone can say what the current setup is without going to look
• Publish a deprecation timeline and actually honour it — and you know whether that is true here
• There is a way to tell whether the last change to this helped

None of this needs a rewrite. Most of it is a morning's work once someone decides to do it.