API versioning: the questions we get asked most

It is rarely the thing that gets a project approved, and often the thing that decides how it goes. The questions about API versioning that come up most often on our calls.

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.

Do we need to care about this?

Version before anyone external depends on you, not after. In practice this is a scheduling problem more than a technical one. The failure mode is not doing it wrong, it is doing it once and assuming it stays done.

Can it wait until after launch?

Occasionally. More often the post-launch version costs several times the pre-launch one. Getting it slightly wrong is survivable. Ignoring it entirely is not.

How do we know it is working?

Publish a deprecation timeline and actually honour it. The teams that handle this well are rarely the ones with the biggest budgets. The version that survives contact with a real deadline is the simple one.

The short version

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
• Additive changes rarely need a new version — and you know whether that is true here
• There is a way to tell whether the last change to this helped

The point is not perfection, it is knowing which of these you have consciously chosen to skip.