API Versioning
API versioning is the practice of managing changes to a public or internal API in a way that allows existing consumers to continue functioning while new capabilities are introduced. Without a versioning strategy, any breaking change — removing a field, changing a response type, altering authentication requirements — can silently break downstream clients. The core challenge is balancing backward compatibility (protecting existing integrations) against forward progress (removing technical debt and shipping new functionality). Versioning must be enforced at both the contract level (what is promised) and the infrastructure level (how requests are routed). Poor versioning discipline is a primary cause of tight coupling between services and extended maintenance burdens.
Key Concepts
- Breaking vs. Non-Breaking Changes: Adding new optional fields or endpoints is generally non-breaking. Removing fields, changing types, renaming parameters, or altering authentication are breaking changes that require a version increment.
- URI Path Versioning: Embedding the version directly in the URL path (e.g.,
/v1/users,/v2/users). Explicit, cache-friendly, and easy to route, but pollutes URL structure and makes version deprecation visible and disruptive. - Header-Based Versioning: Clients specify the desired version via a custom HTTP header (e.g.,
Accept: application/vnd.api+json;version=2). Keeps URLs clean but is less discoverable and harder to test in browsers. - Semantic Versioning (SemVer): A versioning scheme (
MAJOR.MINOR.PATCH) where major version bumps signal breaking changes, minor bumps signal backward-compatible additions, and patch bumps signal bug fixes. - Deprecation Policy: A clearly communicated timeline for when old API versions will be sunset, giving consumers time to migrate. Typically includes deprecation headers, changelogs, and migration guides.
Common Patterns or Tools
- Version Negotiation via Content Negotiation: Using the
Acceptheader to negotiate format and version simultaneously, following REST principles. - Sunset Header: The
SunsetHTTP response header (RFC 8594) allows servers to signal to clients when a deprecated endpoint will be removed. - API Gateway Version Routing: Routing requests to different backend implementations based on version, allowing old and new code to coexist during migration periods.
- Contract Testing: Automated tests that verify a provider’s API continues to fulfill the contracts expected by its consumers, catching breaking changes before deployment.