API versioning is contract management, not a technical formality
Why every API needs a versioning policy, and what happens to integrations when there is none.
Companies that actively build integrations between systems eventually run into the same situation. A team makes a change to one service - and something elsewhere breaks. The investigation takes hours, sometimes days. Nobody is formally at fault: each side did something reasonable, but nobody thought through the downstream effects.
The root cause is almost always the same - no management of API versions as contracts.
What an API contract actually is
When system A calls system B, it relies on a specific behaviour. A specific request format, a specific response format, a specific meaning for each field. That is the contract.
If B changes and breaks the contract, A breaks. If B changes quietly, A breaks unexpectedly - at any point, not necessarily right after the change.
Versioning is the way of saying: "we changed the behaviour, but the old version is still available at the old address." That gives consumers of the API time to adapt, instead of forcing them to change immediately.
Why this matters to a leader
Every unmanaged dependency between systems is hidden debt. It is invisible while everything works. But with every change to any system, someone has to hold the entire dependency graph in their head and reason about what will break.
The more integrations, the more fragile the system. The more expensive each change. The slower the team moves.
Without an API versioning policy, an organisation is effectively saying: "all our integrations are one large monolith, just distributed." That is worse than a normal monolith, because the dependencies are not visible statically.
What minimal discipline looks like
Most companies do not need a complex system. A few principles are enough.
First: every API used by other systems or partners has an explicit version number in the URL or in a header. This is visible, transparent, and findable in code.
Second: there is a support policy - how long a previous version lives after a new one ships. Six months, a year - depends on context. But it exists and is known to consumers.
Third: breaking changes only go out in a new version. No quiet edits to existing behaviour.
Fourth: there is a registry - a list of which APIs exist, who consumes them, and what the current version is. This can be a simple table, not necessarily an expensive platform.
Where this breaks in practice
The most common failure point is internal APIs between teams inside the same company. Because everyone is internal, it feels like you can coordinate on the fly. In practice, every update to an internal service requires coordination and breaks something unexpected.
The second failure point is integrations with partners and external systems. Here, breaking a contract can cost not just development time, but reputation and money.
Questions to check your position
If you want to understand how mature your API discipline is:
- Do your APIs have explicit versions?
- Is there a registry - who calls what?
- Who decides that a change breaks a contract?
- How long do you support old versions?
- How do consumers learn about changes?
If the answers are unclear, you have integrations but no management of them. With a small number of connections this is tolerable. With ten or more it becomes a source of operational fragility.