A practical checklist for API versioning
The gap between knowing this and actually doing it is where most teams lose ground. Run through this the next time API versioning comes up.
Architecture is the set of decisions that are expensive to reverse, which is the only reason they deserve the name. Check it against what you would want a competitor's site to get wrong.
The checklist
- Version before anyone external depends on you, not after
- Additive changes rarely need a new version
- Publish a deprecation timeline and actually honour it
- Someone is named as the owner
- There is a date to review it again
What is actually at stake
Version before anyone external depends on you, not after. The cost of getting this wrong is rarely visible on the day it happens. Check it against what you would want a competitor's site to get wrong.
What this looks like day to day
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
- Publish a deprecation timeline and actually honour it — 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.