Getting started with API versioning
The gap between knowing this and actually doing it is where most teams lose ground. A short on-ramp to API versioning for teams who have not touched it before.
The right architecture for a team of three is the wrong one for a team of thirty, and vice versa. It is worth deciding this deliberately rather than inheriting whatever the last person set up.
What is actually at stake
Version before anyone external depends on you, not after. There is a version of this that is over-engineered, and it is worth avoiding. Assume whoever inherits this will have half your context and none of your patience.
Your first week
- Find out what is already in place
- Additive changes rarely need a new version
- Change one thing and measure it
Publish a deprecation timeline and actually honour it. Getting it slightly wrong is survivable. Ignoring it entirely is not. The failure mode is not doing it wrong, it is doing it once and assuming it stays done.
What this looks like day to day
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
Most of the value here comes from doing the first two things, not all of them.