API versioning: the part nobody talks about in enterprise systems

API versioning is one of those topics everyone has an opinion on — yet very few organisations truly manage. It is quickly agreed upon in meetings, added to documentation and often implemented with the assumption that “we’ll deal with it later”.

The problem is that versioning decisions rarely fail immediately. They fail months later, usually at the worst possible moment.

And by then, the cost of reversing them is high.

Versioning is not a technical detail

In theory, versioning is part of API design. In practice, it is a long-term organisational commitment.

Introducing a new API version does not just mean exposing a new endpoint. It also implies:

How long previous versions will remain active
Which teams will continue supporting them
When and under what conditions they will be retired

If these questions are not answered upfront, versioning is not a solution — it is deferred complexity.

The most common reality in the field

Over time, many organisations end up with an API landscape that looks like this:

v1 is still active
v2 is partially adopted
v3 exists on a roadmap
None can be fully retired

This is often blamed on a lack of discipline. In reality, the causes are structural:

Clients that cannot be upgraded
External partner dependencies
Confusion between versioning and backward compatibility

The API surface grows, but control diminishes.

The real question: new version or behaviour management?

In production systems, the central question should be:

Does this change truly require a new version, or can we evolve behaviour in a controlled way?

Changes such as:

Adding new fields
Supporting optional headers
Extending response formats

often do not require a new version — if managed correctly. Teams that fail to make this distinction default to version increments, quickly creating an unmanageable API landscape.

Method debates miss the point

Versioning discussions often focus on implementation choices:

URL-based?
Header-based?
Content negotiation?

These are valid technical considerations, but rarely decisive in production. The decisive factor is whether the chosen approach aligns with operational reality.

Field observations consistently show:

URL-based versioning works best for public APIs
Header-based approaches fit internal services
Content negotiation offers power at significant operational cost

There is no universally correct method — only contextually appropriate ones.

The hidden cost of versioning: retirement

The real cost of versioning becomes visible when teams attempt to retire an old version.

At that point, uncomfortable questions arise:

Who is still using this version?
Is this endpoint truly unused?
What business processes will break if we turn it off?

Without clear answers, old versions never disappear. Systems do not remain backward compatible — they become frozen.

What works in production

Teams that manage versioning successfully treat it as behaviour management rather than numbering.

Common traits include:

A deliberately limited number of active versions
Clear deprecation plans defined upfront
Heavy reliance on gateways and observability
Measured client behaviour instead of assumptions

This approach enables evolution without uncontrolled growth.

Clear takeaways for decision makers

When versioning is discussed, these questions must be explicitly addressed:

When will this version be retired?
Who decides when to retire it?
What happens if clients do not migrate?
Can we observe real usage?

Without clear answers, versioning introduces risk rather than progress.

Final thought

API versioning is not a design pattern. It is contract management.

Done well, it enables safe change. Done poorly, it amplifies complexity.

And in most failed cases, the issue is not the chosen method but the consequences nobody wanted to discuss.

Frequently asked questions

What are the API versioning strategies?

The main API versioning strategies are URI versioning (/v1/users), header versioning (Accept: application/vnd.api.v1+json), query parameter versioning (?version=1) and content negotiation. Each has advantages and disadvantages. URI versioning is the most common and intuitive. Header versioning keeps URLs clean but makes testing and debugging harder.

Should URI versioning or header versioning be preferred?

The choice depends on the use case. URI versioning (/v1/, /v2/) is more visible, cache-friendly and easier to debug — most enterprise APIs prefer this method. Header versioning appeals more to RESTful purists and keeps the URL structure clean, but can complicate API gateway configuration. A pragmatic approach: use URI versioning for public APIs and header versioning for internal APIs.

When should old API versions be deprecated?

The API deprecation strategy depends on these factors: the number of active consumers, SLA commitments and migration complexity. A typical approach: provide a sunset period of at least 6–12 months after the new version is released, add deprecation headers (Sunset, Deprecation), notify consumers proactively, and remove the version when usage metrics approach zero. In enterprise environments, 12–24 months is more common.

How are breaking changes managed?

Breaking changes such as adding required fields, removing fields or changing types require a new major version. Additive changes (new optional fields, new endpoints) can be made within a minor version or the current version. Breaking changes should be detected early through API design review processes, consumer impact analysis should be conducted and migration guides should be prepared. Backward compatibility should be verified automatically with contract testing.