Signs it is time to revisit API versioning
The version of this that works is simpler than the version most people imagine. A few signals that API versioning is due some attention.
The right architecture for a team of three is the wrong one for a team of thirty, and vice versa. Assume whoever inherits this will have half your context and none of your patience.
The signals
- Nobody can say when it was last reviewed
- The answer depends on who you ask
- Version before anyone external depends on you, not after
- Additive changes rarely need a new version
The practical version
Publish a deprecation timeline and actually honour it. The reasoning matters more than the rule, because the rule has exceptions. It rarely shows up as a line item, which is exactly why it slips.
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
- 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
If you are not sure where your systems currently stand on this, it takes us about an hour to find out.