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: 'alice@example.com',
  });
});

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 curl or 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.

推荐订阅源

DEV Community