API Versioning
API versioning is the practice of managing changes to an API over time by exposing multiple versions of it, so existing clients keep working while new capabilities are introduced.
Definition
API versioning is the practice of managing changes to an API over time by exposing multiple versions of it, so existing clients keep working while new capabilities are introduced.
Overview
As a REST API or GraphQL service evolves, breaking changes are sometimes unavoidable — renaming a field, changing a response shape, or removing an endpoint. API versioning lets a provider ship those changes without immediately breaking every client that depends on the old behavior, by keeping the previous version available (often for a defined deprecation period) alongside the new one. There are several common approaches: URI versioning embeds the version in the path (e.g. /v1/users, /v2/users) and is the most visible and cache-friendly option; header versioning passes the version in a custom or Accept header, keeping URLs stable; and query-parameter versioning passes it as ?version=2. GraphQL APIs often take a different approach entirely, favoring additive, non-breaking schema evolution with field deprecation notices over discrete version numbers. Good versioning strategy pairs technical mechanism with process: a clear deprecation policy, sunset dates communicated in advance (often via response headers), and changelogs so client teams can plan migrations. It is also closely tied to backward-compatible design at the API Gateway layer, where routing rules can direct different version paths to different backend implementations during a transition period.
Key Concepts
- Allows breaking changes to ship without immediately disrupting existing clients
- Common strategies: URI path, custom headers, and query parameters
- Deprecation policies and sunset dates communicate when old versions will be retired
- API gateways can route different version paths to different backend implementations
- GraphQL APIs often favor additive schema evolution over explicit version numbers
- Semantic versioning principles help clients understand the scope of changes
- Requires coordination between backend teams and client-side consumers