Five mistakes teams make with API versioning
Teams tend to reach for this after something has already gone wrong. These are the ones we run into repeatedly when we audit API versioning.
Architecture is the set of decisions that are expensive to reverse, which is the only reason they deserve the name. The version that survives contact with a real deadline is the simple one.
The mistakes we see most
- Treating it as a launch task rather than an ongoing one
- Assuming someone else already owns it
- Version before anyone external depends on you, not after
- Additive changes rarely need a new version
- Never checking whether the fix actually worked
Publish a deprecation timeline and actually honour it. There is a version of this that is over-engineered, and it is worth avoiding. It is the sort of thing that looks like polish right up until it costs you an enquiry.
What to do next
How to tell if yours is fine
The right architecture for a team of three is the wrong one for a team of thirty, and vice versa. 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
Most of the value here comes from doing the first two things, not all of them.