API Versioning Strategies: URL Path, Query Params, and Headers Compared
Every API evolves. Fields get renamed, endpoints get restructured, response shapes change. If you have clients depending on your API, breaking changes are a serious problem — and versioning is the mechanism that lets you ship those changes without burning everyone downstream.
The trouble is, there's no single "right" way to version an API. Three patterns dominate the industry, each with real trade-offs. Let's break them down with concrete examples so you can make an informed choice.
Strategy 1: URL Path Versioning
The most common approach embeds the version directly in the URL path:
GET /v1/users/42
GET /v2/users/42
Implementation (Express.js)
const express = require('express');
const app = express();
const v1Router = express.Router();
v1Router.get('/users/:id', (req, res) => {
res.json({ id: req.params.id, name: 'Alice' }); // old shape
});
const v2Router = express.Router();
v2Router.get('/users/:id', (req, res) => {
res.json({
id: req.params.id,
firstName: 'Alice', // renamed in v2
lastName: 'Smith',
email: '[email protected]',
});
});
app.use('/v1', v1Router);
app.use('/v2', v2Router);
Pros:
- Immediately visible in browser, logs, and dashboards — no mystery about which version a request hit
- Easy to route at the load balancer or CDN level
- Simple to document and test
Cons:
- Violates REST purists' view that a URL should identify a resource, not a version of a resource
- Clients must update base URLs when upgrading
- Can lead to copy-paste codebases if v2 is largely identical to v1
Strategy 2: Query Parameter Versioning
The version is passed as a query string parameter:
GET /users/42?version=1
GET /users/42?version=2
Implementation
app.get('/users/:id', (req, res) => {
const version = parseInt(req.query.version) || 1;
if (version >= 2) {
return res.json({ id: req.params.id, firstName: 'Alice', lastName: 'Smith' });
}
return res.json({ id: req.params.id, name: 'Alice' });
});
Pros:
- A single URL structure — easier to share and link
- Optional parameter means you can default to latest (or earliest stable) without breaking callers that omit it
Cons:
- Query params get lost in caches — proxy caches must be explicitly configured to vary on this parameter
- Easy to forget or accidentally omit, silently calling the wrong version
- Less idiomatic; most major APIs have moved away from this pattern
Strategy 3: Header-Based Versioning
The version is communicated via a custom request header:
GET /users/42
Accept-Version: 2
Or using the standard Accept header with a vendor media type:
GET /users/42
Accept: application/vnd.myapi.v2+json
Implementation
app.get('/users/:id', (req, res) => {
const version = parseInt(req.headers['accept-version']) || 1;
if (version >= 2) {
return res.json({ id: req.params.id, firstName: 'Alice', lastName: 'Smith' });
}
return res.json({ id: req.params.id, name: 'Alice' });
});
Pros:
- Clean URLs — the resource identifier is pure, version is metadata
- Semantically correct from a REST standpoint
- Works well with content negotiation for nuanced version control
Cons:
- Headers are invisible in the browser address bar — harder to debug at a glance
- Trickier to test with simple tools like
curlor Postman without extra setup - Cache keys must include the header or you'll serve the wrong version from cache
Which Should You Choose?
Here's a practical rule of thumb:
Building a public API with many external consumers? Use URL path versioning. It's the most legible, easiest to document, and what most developers expect.
Internal API with controlled clients? Header versioning is clean and keeps URLs tidy.
Rapid prototype or small project? Query params are the quickest to implement, but plan to migrate if the API grows.
Regardless of strategy, be explicit about your deprecation policy. Set a sunset date, communicate it in a Sunset response header, and keep old versions alive long enough for clients to migrate:
Sunset: Sat, 31 Dec 2026 23:59:59 GMT
Deprecation: true
Link: <https://api.example.com/v2/users>; rel="successor-version"
Keeping All Versions in Sync Is the Real Work
The versioning strategy is the easy part. The hard part is maintaining documentation, test coverage, and client SDKs across multiple live versions simultaneously.
APIKumo is built for exactly this problem — it lets you manage multiple API versions in a single workspace, auto-generates client code in 26 languages per version, and keeps your docs in sync with your actual requests. When you eventually deprecate v1, you're not digging through a wiki to find what changed — it's all in the collection history.
If you're designing an API that needs to outlast its first iteration (most do), a clear versioning strategy from day one will save you weeks of migration pain later.
SOCIAL SHARE CARD GENERATOR