API versioning: what to get right first

Most teams know this matters. Fewer have decided who owns it. If you only fix one thing about API versioning this quarter, make it the first item below.

The right architecture for a team of three is the wrong one for a team of thirty, and vice versa. It is worth deciding this deliberately rather than inheriting whatever the last person set up.

Start here

Version before anyone external depends on you, not after. It is worth being explicit about, because assumptions differ quietly. Check it against what you would want a competitor's site to get wrong.

Then this

Additive changes rarely need a new version. This is the sort of thing that compounds, quietly, in both directions. The teams that stay on top of it are the ones who put it on a calendar rather than a wish list.

Eventually

Publish a deprecation timeline and actually honour it. Getting it slightly wrong is survivable. Ignoring it entirely is not. The failure mode is not doing it wrong, it is doing it once and assuming it stays done.

What this looks like day to day

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

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