What Is API Versioning? Evolving an Interface Without Breaking It

API versioning lets you introduce breaking changes by running a new version of an interface alongside the old one until clients migrate.

Sometimes a breaking change is unavoidable. API versioning is how you ship it without forcing every client to update at once: expose a new version, keep the old one running, and let consumers move on their own schedule. The cost is maintaining and testing multiple versions until the old one can be retired.

Why version at all

A versioned API can evolve, even with breaking changes, without coordinating every client. Old clients stay on the old version; new clients adopt the new one. This decoupling is essential for public APIs and large microservice estates.

Common strategies

URL path versioning (/v1/, /v2/) - explicit and easy to route.
Header or media-type versioning - keeps URLs stable.
Query-parameter versioning - simple but easy to overlook.
No versioning, only additive changes - viable if you never break.

The cost of multiple versions

Each live version is code you must maintain, test, and secure. Versions accumulate, so a deprecation policy, announce, sunset, remove, is what keeps the surface area from growing without bound.

Testing every supported version

CI has to test each live version, often as a matrix, to ensure none regress while the new one evolves. The pipeline grows with the number of supported versions, which is itself an argument for retiring old ones promptly.

Deploying a new version

A new version usually ships additively, the old one keeps serving, so the deploy itself is non-breaking. The breaking change is contained inside the new version, which makes the rollout safe and the rollback simple.

Version matrices on fast runners

Testing several API versions in parallel is a natural matrix build. Managed runners that scale out (like Latchkey) run those version jobs concurrently so the suite finishes quickly despite the extra coverage.

Key takeaways

API versioning runs new and old interface versions side by side.
It lets you ship breaking changes without forcing a synchronized client update.
Each live version is maintenance and test cost, so deprecate old ones deliberately.