API Versioning Vocabulary: URI vs Header vs Content-Type Versioning
Master API versioning vocabulary — URL path, header, and content-type strategies, semantic versioning, deprecation, sunset headers, breaking changes, and changelog writing.
APIs are contracts between teams, products, and companies. When those contracts change, you need a clear versioning strategy and the language to communicate changes to every consumer. Whether you are designing a public API, writing a deprecation notice, or reviewing a migration guide, the vocabulary in this post will help you sound precise and professional.
Versioning Strategies
URL Path Versioning
URL path versioning embeds the version number directly in the URI: /api/v1/users, /api/v2/users. It is the most visible and widely understood strategy.
“We use URL path versioning —
v1stays live for 18 months afterv2launches so existing clients have time to migrate.”
Advantages: easy to read, easy to route, works with every HTTP client. Disadvantage: a version bump affects the URL of every endpoint, even ones that did not change.
Query Parameter Versioning
Query parameter versioning passes the version as a query string: /api/users?version=2. Less common in REST APIs but seen in some legacy systems.
“Query parameter versioning makes it easy to test different versions in the browser, but it’s messy for client libraries to handle.”
Header Versioning
Header versioning passes the requested version in a custom HTTP request header, for example API-Version: 2. The URL stays clean.
“We switched to header versioning so the URL stays stable and version negotiation happens at the protocol layer.”
Content Negotiation Versioning
Content negotiation uses the Accept header with a vendor media type: Accept: application/vnd.myapp.v2+json. It is the most RESTful approach in theory, but the most complex to implement and debug.
“Content negotiation versioning is elegant but harder to test manually —
curlcalls become verbose quickly.”
Semantic Versioning for APIs
Semantic Versioning (SemVer)
Semantic versioning uses a MAJOR.MINOR.PATCH scheme. For APIs:
MAJOR— a breaking change that requires consumers to updateMINOR— a new, backwards-compatible featurePATCH— a backwards-compatible bug fix
“This is a MINOR release — we’re adding a new optional field. Existing clients don’t need to change anything.”
Breaking Change
A breaking change is any modification that causes existing, correctly written clients to fail. Examples: removing a field, renaming a field, changing a field’s type, requiring a new mandatory parameter.
“Removing the
usernamefield is a breaking change. We need to keep it in the response — mark it as deprecated first, remove it in v3.”
Non-Breaking Change
A non-breaking change (also called a backwards-compatible change) does not affect existing clients. Examples: adding a new optional field, adding a new endpoint, adding a new optional query parameter.
“Adding the
avatarUrlfield is non-breaking. Existing clients will just ignore it.”
Backward Compatibility
Backward compatibility (or backwards compatibility) means old clients continue to work correctly after a change. It is the primary goal of API lifecycle management.
“We guarantee backward compatibility within a major version. If we make a breaking change, we bump the major version.”
API Lifecycle
API Lifecycle Stages
A typical API moves through these stages:
- Design — define the contract: endpoints, request/response shapes, authentication
- Build — implement the API
- Publish — make it available to consumers
- Deprecate — signal that this version or endpoint will be retired
- Retire — shut it down
“The v1 authentication endpoint is in the deprecate stage — it still works, but we’re telling consumers to migrate to v2 now.”
Deprecation Notice
A deprecation notice is a formal announcement that a feature, endpoint, or version will be removed in the future. It gives consumers time to migrate.
“We sent a deprecation notice six months ago. The sunset date is next quarter — at that point, v1 returns
410 Gone.”
Sunset Header
The Sunset HTTP header tells clients the date on which an endpoint or API version will be discontinued. It is standardised in RFC 8594.
“Add a
Sunset: Sat, 01 Jan 2027 00:00:00 GMTheader to all v1 responses so clients can plan their migration.”
Documentation
Changelog
An API changelog documents every change to the API in reverse chronological order. It is the first place a developer looks when something breaks after an update.
Good changelog entries are specific and actionable. Use this format:
## v2.3.0 — 2026-06-04
### Added
- `GET /users/{id}/preferences` — returns user preference settings.
### Changed
- `POST /orders` now accepts an optional `couponCode` field.
### Deprecated
- `GET /users/{id}/settings` — use `/preferences` instead. Removal in v3.0.
### Breaking changes (v3.0 preview)
- `GET /users` will no longer include the `legacyId` field.“Always separate ‘Added’, ‘Changed’, ‘Deprecated’, and ‘Breaking’ sections in your changelog — consumers scan for breaking changes first.”
Migration Guide
A migration guide walks API consumers through the specific steps needed to upgrade from one version to another. It translates breaking changes into actionable instructions.
“We published a v1-to-v2 migration guide with before/after code examples for every breaking change. Adoption rate doubled compared to previous migrations.”
Common API Versioning Phrases
| Phrase | Meaning |
|---|---|
| ”This is a breaking change” | Existing clients will need to update |
| ”We’re deprecating this endpoint” | It still works but will be removed; migrate now |
| ”What’s your sunset timeline?” | When will you shut down the old version? |
| ”We maintain two major versions” | Current and previous are both live |
| ”Add this to the changelog” | Document the change for consumers |
| ”Is this backwards-compatible?” | Will existing clients still work without changes? |
| ”Version negotiation” | How the client and server agree on which version to use |