API Versioning Vocabulary: URI vs Header vs Content-Type Versioning

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 — v1 stays live for 18 months after v2 launches 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 — curl calls 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 update
• MINOR — a new, backwards-compatible feature
• PATCH — 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 username field 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 avatarUrl field 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:

1. Design — define the contract: endpoints, request/response shapes, authentication
2. Build — implement the API
3. Publish — make it available to consumers
4. Deprecate — signal that this version or endpoint will be retired
5. 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 GMT header 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

Navigating the Shifts: A Practical Approach to API Versioning

Let’s face it – APIs evolve. They must evolve. But managing that evolution without disrupting clients is a delicate art. The vocabulary surrounding API versioning can be confusing, particularly when you consider the different strategies for signalling changes. This post aims to clarify those terms and how they fit together, focusing on practical application rather than theoretical definitions. We’ll look at how these concepts play out in real-world scenarios – from code reviews to Slack conversations about upcoming updates.

One of the biggest challenges is communicating versioning decisions effectively. Imagine a developer pushing a change with a new Content-Type: application/v2 header, accompanied by a message saying “Using the latest API!” That’s where precise terminology becomes crucial. A URI versioning strategy, for example, relies on modifying the URL path – /api/v2/users – to indicate a different version. This is often preferred for simple changes as it’s relatively easy to understand and implement. However, relying solely on URIs can lead to confusion if multiple versions are deployed simultaneously. Conversely, using header versioning – like the Content-Type example above – allows for more flexibility but requires clients to actively monitor headers for updates. Content-Type versioning is less common now due to evolving standards and potential ambiguity around content negotiation.

A key concept related to all these strategies is semantic versioning (SemVer), which provides a structured approach to communicating the nature of changes. A v2 change might signify backwards compatibility, whereas a v3 could indicate breaking changes requiring client updates. Furthermore, you’ll frequently see deprecation headers or sunset headers – HTTP response headers like X-Api-Deprecated: true – used to signal that an endpoint will be removed in the future, allowing developers time to migrate their code.

Understanding these distinctions is crucial for effective communication within your team and with external clients. It’s not just about choosing a versioning strategy; it’s about conveying why that strategy was chosen and what changes are expected. A clear changelog detailing the impact of each version is absolutely essential – documenting both functional additions and any breaking modifications.

Here’s an example demonstrating how URI versioning might be used in a curl command:

curl -H "Content-Type: application/v2+json" https://api.example.com/users?limit=10

This command explicitly requests the API using version 2, providing clarity to the server and any monitoring systems tracking API usage. This level of detail is critical for managing the complexities of modern APIs and ensuring smooth transitions between versions.