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
Use Cases
Frequently Asked Questions
From the Blog
API Design Principles: Resources, Contracts, Versioning
An API is a contract you will be held to long after the code behind it is rewritten, so design decisions about resources, errors, pagination and versioning outlive almost everything else you build. This guide covers the choices that determine whether clients break when you change things.
Read More ProgrammingGo modules explained: versioning, upgrades and vendoring
Work with Go modules deliberately. Minimal version selection is why your build does not drift and why an upgrade is an explicit edit, go.sum is an integrity record rather than a lockfile, and the major-version-in-the-path rule is what makes breaking upgrades survivable.
Read More ProgrammingWhat Is npm and How Package Management Works
npm is the default package manager for Node.js, installing and versioning the libraries your project depends on. Here is how packages, package.json, and lockfiles work.
Read More AI & TechnologyMLOps Explained: Deploy ML Models to Production
MLOps deploys ML models to production by combining DevOps practices with data and model versioning, automated pipelines, and drift monitoring.
Read More