Glossary/API Versioning
API & Integration
1 min read
Share:

What is API Versioning?

TL;DR

API versioning is the practice of maintaining multiple versions of an API simultaneously to support existing clients while evolving the API for new capabilities.

API versioning is the practice of maintaining multiple versions of an API simultaneously to support existing clients while evolving the API for new capabilities. It's the contract management layer of API development.

Versioning strategies: URL path versioning (/v1/users, /v2/users — most common, most explicit), Query parameter versioning (?version=2 — flexible but less discoverable), Header versioning (Accept: application/vnd.api.v2+json — clean URLs, harder to test), and Content negotiation (different media types for different versions).

Versioning policy: how long are old versions supported? Industry standard: 12-24 months of support after deprecation notice. Breaking changes (field removal, type changes, behavior changes) always require a new version.

Why It Matters

Breaking API changes without versioning destroys client trust and causes outages. A well-versioned API lets you evolve while maintaining backward compatibility — essential for platform businesses.

Frequently Asked Questions

What is API versioning?

Maintaining multiple API versions simultaneously to support existing clients while evolving for new ones. Prevents breaking changes from disrupting integrations.

Which versioning strategy is best?

URL path versioning (/v1/, /v2/) is most common and most explicit. It's easy to route, test, and document. Header-based versioning is cleaner but harder for developers to discover and test.

Related Terms

Need Expert Help?

Richard Ewing is a Product Economist and AI Capital Auditor. He helps companies translate technical complexity into financial clarity.

Book Advisory Call →