API versioning for small teams

This is one of those topics that looks small until it costs you something. Most advice about API versioning assumes a team that does not exist at your size. Here is the version that does not.

Most systems fail at the seams rather than inside any one component. If two people in the business would answer this differently, that gap is the actual problem.

What to keep

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.

What to drop

Process that exists to coordinate ten people is overhead when there are two of you. This is the sort of thing that compounds, quietly, in both directions.

The practical version

Publish a deprecation timeline and actually honour it. This is the sort of thing that compounds, quietly, in both directions. If two people in the business would answer this differently, that gap is the actual problem.

In practice

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

If any of that sounds like a description of your current setup, it is fixable.