What Is API Versioning? | Vantage
API Versioning API versioning is the practice of managing changes to a public or shared API over time in a way that allows existing clients to continue functioning while new capabilities are introduced. Versioning strategies include URL versioning (/v1/, /v2/), header versioning (Accept: application/vnd.api+json;version=2), query parameter versioning (?version=2), and semantic versioning for library APIs (1.0.0, 2.0.0). The goal is to separate the deployment of API changes from the migration of API consumers.
Why api versioning matters
APIs are contracts between a server and its clients. Breaking changes — removing fields, changing response shapes, making optional fields required — break consumers who built against the old contract. Versioning allows producers to evolve APIs without forcing all consumers to migrate simultaneously. For internal APIs (microservices), this enables independent deployment. For external APIs (developer platforms), this is a commercial necessity — breaking a customer's integration is a severe trust violation.
How it works
When a breaking change is needed, a new version is introduced that includes the change. The old version continues to be supported for a deprecation period (typically 6-24 months for external APIs). Consumers migrate at their own pace. Version sunset dates are communicated in advance. Monitoring tracks which version each consumer uses, enabling informed deprecation decisions. Non-breaking changes (adding optional fields, adding endpoints) do not require a new version.
Common mistakes
Breaking changes in the same version — adding required fields, removing fields, or changing response shapes without bumping the version
No deprecation timeline — consumers cannot migrate without knowing when the old version goes away
Versioning too early — creating v2 before v1 has real consumers creates maintenance burden for no benefit
Versioning the entire API when only one endpoint changed — fine-grained versioning by endpoint reduces migration scope for consumers
No consumer inventory — you cannot deprecate a version safely without knowing who is using it
Related terms
How Vantage relates
When API versioning decisions are made, Vantage context collection can store the API contracts and versioning strategy as project context. Generated tickets for API-related features can include the versioning requirement — whether the change is additive (no new version needed) or breaking (requires version bump) — so engineers know the deprecation work required alongside the feature work.