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