API Versioning Strategies

How you version your API determines how painful it is to evolve it — and how painful it is for your clients to migrate. This guide covers every versioning approach with real request examples, a clear pros/cons matrix, and the Sunset/deprecation headers that make migrations manageable.

Strategy 1: URL Path Versioning

The version is part of the URL path. Used by Stripe, Twilio, GitHub, and most public APIs.

GET  https://api.example.com/v1/users/42
POST https://api.example.com/v2/users

# Express routing — mount per-version routers
import express from 'express';
import v1Routes from './routes/v1';
import v2Routes from './routes/v2';

const app = express();
app.use('/v1', v1Routes);
app.use('/v2', v2Routes);

# Or use a single router with version middleware
app.use('/v:version', (req, res, next) => {
  req.apiVersion = parseInt(req.params.version);
  next();
}, mainRouter);

# nginx — route by URL prefix to versioned backends
location /v1/ {
  proxy_pass http://api-v1:3000/;
}
location /v2/ {
  proxy_pass http://api-v2:3001/;
}
# Default (no version prefix) → latest stable
location /api/ {
  proxy_pass http://api-v2:3001/;
}

Strategy 2: Request Header Versioning

The URL stays clean; clients declare the version in a request header.

# Option A: custom header
GET /users/42
X-API-Version: 2

# Option B: Accept header (content negotiation, RFC 6838)
GET /users/42
Accept: application/vnd.acme.v2+json

# Option C: Stripe-style date-based versions
GET /users/42
Stripe-Version: 2024-06-20

// Express middleware — extract version from header
function apiVersionMiddleware(req, res, next) {
  const headerVersion = req.headers['x-api-version'];
  const acceptVersion  = (req.headers['accept'] ?? '')
    .match(/vnd\.acme\.v(\d+)\+json/)?.[1];

  req.apiVersion = parseInt(headerVersion ?? acceptVersion ?? '1');

  // Tell CDN to cache separately per version
  res.setHeader('Vary', 'X-API-Version, Accept');
  next();
}

app.use(apiVersionMiddleware);

app.get('/users/:id', (req, res) => {
  if (req.apiVersion >= 2) {
    return res.json(buildUserResponseV2(req.params.id));
  }
  return res.json(buildUserResponseV1(req.params.id));
});

Strategy 3: Query Parameter Versioning

Simple but mixes routing concerns with filtering. Avoid for public APIs.

GET /users/42?version=2
GET /users/42?v=2&format=json

# Simple to implement but has problems:
# - Easy to accidentally omit from generated URLs
# - Some proxies strip query params from cache keys
# - Harder to route at the infrastructure level
# - Mixes version (routing concern) with filters (query concern)

Sunset & Deprecation Headers

// Express middleware — attach deprecation headers to v1 responses
function deprecationHeaders(req, res, next) {
  // Deprecation: when this version was deprecated (past date)
  res.setHeader('Deprecation', 'Mon, 01 Jul 2024 00:00:00 GMT');

  // Sunset: when this version will be removed (future date)
  res.setHeader('Sunset', 'Fri, 01 Jan 2026 00:00:00 GMT');

  // Link to migration guide
  res.setHeader(
    'Link',
    '<https://docs.example.com/v2/migration>; rel="successor-version", ' +
    '<https://docs.example.com/changelog>; rel="deprecation"'
  );

  next();
}

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

// Client-side: detect Sunset header and warn developers
async function apiRequest(url: string, options?: RequestInit) {
  const response = await fetch(url, options);

  const sunset = response.headers.get('Sunset');
  if (sunset) {
    const sunsetDate = new Date(sunset);
    const daysUntil  = Math.floor(
      (sunsetDate.getTime() - Date.now()) / (1000 * 60 * 60 * 24)
    );
    console.warn(
      `[API] Warning: This endpoint is deprecated and will be removed ` +
      `in ${daysUntil} days (${sunset}). ` +
      `See Link header for migration guide.`
    );
  }

  return response;
}

Pros & Cons Comparison

Breaking vs Non-Breaking Changes

Migration Checklist

# API Version Migration Checklist
# --------------------------------
# 1. Announce deprecation with at least 6-month timeline
#    - Blog post, email to API key holders, changelog entry
#    - Start sending Deprecation + Sunset headers immediately

# 2. Publish migration guide
#    - Diff of breaking changes
#    - Before/after code examples for each change
#    - Link in Sunset Link header

# 3. Track adoption via analytics
#    - Log X-API-Version / URL prefix per API key
#    - Identify clients still on old version at 3mo, 1mo, 1wk marks

# 4. Email stragglers
#    SELECT api_key, last_seen FROM api_requests
#    WHERE version = 'v1' AND last_seen > NOW() - INTERVAL '30 days';

# 5. Sunset the version
#    - Return 410 Gone with migration URL
#    - Keep route handler, just return error
#    app.use('/v1', (req, res) => res.status(410).json({
#      error: {
#        code: 'VERSION_SUNSET',
#        message: 'API v1 has been removed. Please migrate to v2.',
#        migration_guide: 'https://docs.example.com/v2/migration',
#      }
#    })));