Technology context: Microsoft Azure API Management (APIM)
Azure API Management makes it straightforward to create API versions and revisions. The difficult part is not creating v2.
It is operating v1 and v2 safely, sometimes for years, across consumers, policies, schemas, environments and deployment pipelines.
At that point, API versioning stops being an APIM configuration feature and becomes an operating model.
Version the contract, not the implementation
A backend change does not automatically require a new API version.
With Azure APIM, routing can change, policies can evolve, authentication can be redesigned, dependencies can be replaced and resilience can improve without necessarily changing the consumer-facing contract.
A useful principle is:
Version the consumer contract, not the implementation.
A new API version should represent a meaningful contract boundary, particularly where existing consumers could be affected structurally, behaviourally or semantically.
This prevents unnecessary version proliferation.
Versions and revisions serve different purposes
Azure APIM provides both versions and revisions, but they should not be treated as interchangeable.
A version represents a consumer-visible contract change.
A revision allows controlled evolution of an existing version while preserving that contract.
For example, an API operation may retain the same external contract while its internal policy becomes more sophisticated: improved backend routing, timeout handling, dependency checks or failure mapping.
That is usually a revision problem, not a versioning problem.
The principle works both ways: revisions should not be used to hide breaking changes.
Versions protect consumers. Revisions allow the implementation to evolve safely.
Every version creates an operational commitment
In APIM, a new version can create another:
- API contract and schema set
- policy surface
- deployment artifact
- test surface
- monitoring surface
- documentation set
- consumer migration path
- retirement obligation
The complexity increases further in layered API estates where experience, process and system APIs evolve independently.
Without clear ownership, teams can quickly lose visibility of which upstream API version depends on which downstream contract.
The risk is not simply technical complexity.
It is loss of architectural clarity.
Source control must remain authoritative
The Azure portal makes API changes easy.
That is useful for investigation and controlled experimentation, but dangerous if APIM runtime configuration begins to diverge from source-controlled artifacts.
A mature APIM estate should be able to answer:
Can this environment be reproduced from source control?
If the answer is no, environment drift has already become part of the operating model.
Persistent changes to policies, operations, schemas and API definitions should therefore flow back into the governed delivery lifecycle.
APIOps automation helps enormously, but automation is only reliable when the source of truth is clear.
Compatibility is more than schema compatibility
Breaking changes are not limited to removing properties from an OpenAPI definition.
Consumers can also be affected when:
- optional values become mandatory
- validation becomes stricter
- error behaviour changes
- latency changes materially
- a property’s meaning changes while its type remains unchanged
Contract validation and OpenAPI linting are valuable, but they cannot identify every semantic change.
Compatibility remains partly an architectural responsibility.
Deprecation needs an operating model
Azure APIM can host several API versions simultaneously.
That capability should not become a reason to retain them indefinitely.
A healthy lifecycle distinguishes between versions that are preferred, supported, deprecated and retired.
Consumers should understand what replaces a deprecated version, what must change and how long the transition period will last.
Supporting multiple versions is sometimes necessary.
Supporting every historic version permanently is usually a governance problem.
Observability should support lifecycle decisions
Aggregate APIM traffic is not enough when several versions coexist.
Retirement decisions require visibility into which versions are still used, which operations are active and which subscriptions or consumers depend on them.
Version-aware telemetry turns retirement from assumption into evidence.
It can reveal that an apparently obsolete version still supports a critical integration-or that a deprecated version has had no meaningful usage for months.
Shared policies need lifecycle discipline too
APIM policy fragments, shared schemas and common policies reduce duplication, but they also introduce shared dependencies.
A change to a common fragment can affect several APIs and versions simultaneously.
Reuse should reduce duplication without removing change boundaries.
Shared APIM components therefore need compatibility and versioning discipline of their own.
The numbering scheme is not the strategy
Whether an organisation chooses URL versioning, headers or another mechanism matters less than whether the lifecycle is governed.
The more important questions are:
Can every active API contract be identified?
Can APIM runtime state be recreated from governed artifacts?
Do we know who consumes each version?
Can backend implementation change without unnecessary contract change?
Can breaking behaviour be detected?
Can obsolete versions be retired confidently?
If the answer is yes, the organisation has an API versioning strategy.
If not, it mostly has version numbers.
Closing perspective
Azure API Management provides strong mechanisms for versions, revisions, policies and controlled promotion.
Those mechanisms do not create lifecycle discipline by themselves.
The real challenge is balancing consumer stability with platform evolution through clear contract ownership, reproducible deployment, compatibility controls, observability and deliberate retirement.
The most useful question is therefore not:
“How do we create the next API version in APIM?”
It is:
“What long-term operational commitment are we creating when we do?”