REST API Versioning Strategies: URL, Header & Content Negotiation

API versioning lets you evolve your API without breaking existing clients. Each strategy has trade-offs between visibility, REST purity, and developer experience. This guide covers all four approaches with working examples and a pros/cons comparison.

URL Path Versioning (Most Common)

The version is embedded in the URL path. Simple to understand, route, and document. Used by Stripe, GitHub, and most major public APIs:

# URL versioning — version in path prefix
GET https://api.example.com/v1/users/42
GET https://api.example.com/v2/users/42

# Express router setup — mount each version separately
import express from 'express';
import { v1Router } from './routes/v1';
import { v2Router } from './routes/v2';

const app = express();

app.use('/v1', v1Router);   // Legacy — maintained until 2027-01-01
app.use('/v2', v2Router);   // Current stable version

# Kong API Gateway routing by path prefix
services:
  - name: api-v1
    url: http://api-service:8080/v1
    routes:
      - paths: ['/v1']
  - name: api-v2
    url: http://api-service:8080/v2
    routes:
      - paths: ['/v2']

Header Versioning & Content Negotiation

Keep URLs clean by encoding the version in a request header or the Accept header. Both approaches require client-side discipline but produce cleaner resource URIs:

# Option A: Custom header versioning
GET /users/42
API-Version: 2
Authorization: Bearer eyJ...

# Option B: Content negotiation (most RESTful)
GET /users/42
Accept: application/vnd.example.v2+json
Authorization: Bearer eyJ...

# Express middleware — read version from header or Accept
function resolveVersion(req: Request, res: Response, next: NextFunction) {
  // Try custom header first
  let version = req.headers['api-version'] as string;

  // Fall back to Accept header content negotiation
  if (!version) {
    const accept = req.headers.accept ?? '';
    const match = accept.match(/application\/vnd\.example\.v(\d+)\+json/);
    version = match?.[1] ?? '1';   // default to v1
  }

  req.apiVersion = parseInt(version, 10);
  next();
}

app.use(resolveVersion);

app.get('/users/:id', (req: any, res) => {
  if (req.apiVersion >= 2) return userHandlerV2(req, res);
  return userHandlerV1(req, res);
});

Sunset & Deprecation Headers

Always announce deprecated versions via response headers so automated tooling and monitoring can alert developers before the cutoff date:

// Middleware: add deprecation headers to all v1 responses
function deprecationWarning(req: Request, res: Response, next: NextFunction) {
  // RFC 8594 Sunset header — machine-readable cutoff date
  res.set('Sunset', 'Sat, 01 Jan 2027 00:00:00 GMT');

  // Deprecation header — when deprecation was announced
  res.set('Deprecation', 'Mon, 01 Jul 2026 00:00:00 GMT');

  // Link to migration guide
  res.set('Link', [
    '<https://devplaybook.cc/api/migrate-v1-to-v2>; rel="successor-version"',
    '<https://devplaybook.cc/api/sunset>; rel="sunset"',
  ].join(', '));

  next();
}

// Apply only to v1 routes
app.use('/v1', deprecationWarning, v1Router);

// Response headers clients will see on every v1 call:
// Sunset: Sat, 01 Jan 2027 00:00:00 GMT
// Deprecation: Mon, 01 Jul 2026 00:00:00 GMT
// Link: <.../migrate-v1-to-v2>; rel="successor-version"

Versioning Strategy Comparison