How to get API versioning right
Every audit we run turns up some version of this. The short answer to API versioning is that it is mostly a sequence of small decisions, not one big one.
Most systems fail at the seams rather than inside any one component. It is the sort of thing that looks like polish right up until it costs you an enquiry.
What it costs to ignore
Version before anyone external depends on you, not after. None of that requires a large budget, only a decision and someone to own it. Doing this properly once is usually cheaper than doing it approximately three times.
The steps
- Establish what you have today before changing anything
- Additive changes rarely need a new version
- Publish a deprecation timeline and actually honour it
- Write down the decision so the next person does not re-litigate it
Publish a deprecation timeline and actually honour it. The teams that handle this well are rarely the ones with the biggest budgets. It is the sort of thing that looks like polish right up until it costs you an enquiry.
Where to go from here
The short version
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
Most of the value here comes from doing the first two things, not all of them.