Before you invest in API versioning

This is cheap to get right at the start and expensive to retrofit. Before you spend anything on API versioning, it is worth confirming a few things are already true.

The right architecture for a team of three is the wrong one for a team of thirty, and vice versa. The version that survives contact with a real deadline is the simple one.

Prerequisites

• You can describe the outcome you want in one sentence
• Someone owns it after the work is done
• Version before anyone external depends on you, not after
• You have a way to tell whether it worked

Common failure modes

Additive changes rarely need a new version. It is worth being explicit about, because assumptions differ quietly. It rarely shows up as a line item, which is exactly why it slips.

Publish a deprecation timeline and actually honour it. Small and consistent beats large and occasional here. The teams that stay on top of it are the ones who put it on a calendar rather than a wish list.

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
• 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

Pick the one that would hurt most if it failed, and start there.