API Versioning

Overview

Version your APIs from day one. Never break existing clients.

Breaking changes without versioning destroy client trust. Version APIs explicitly, support multiple versions gracefully, and deprecate with ample warning.

When to Use

• Designing new API endpoints
• Adding or modifying existing endpoints
• Making changes that could break clients
• Planning API evolution strategy
• Reviewing API design decisions

The Iron Rule

NEVER make breaking changes to a released API version.

No exceptions:

• Not for "it's a bug fix"
• Not for "nobody uses that field"
• Not for "we'll notify clients"
• Not for "it's just internal"
• Not for "the old way was wrong"

Breaking changes require a new version. Always.

Detection: What's a Breaking Change?

Versioning Strategies

1. URL Path Versioning (Recommended)

// ✅ CORRECT: Version in URL path
// /api/v1/users
// /api/v2/users

app.get('/api/v1/users', handleUsersV1);
app.get('/api/v2/users', handleUsersV2);

Pros: Explicit, cacheable, easy to route Cons: URL proliferation

2. Header Versioning

// ✅ CORRECT: Version in Accept header
// Accept: application/vnd.api+json; version=1

app.get('/api/users', (req, res) => {
  const version = parseVersion(req.headers.accept);
  if (version === 1) return handleUsersV1(req, res);
  if (version === 2) return handleUsersV2(req, res);
  return res.status(406).json({ error: 'Unsupported version' });
});

Pros: Clean URLs Cons: Hidden, harder to test, caching complexity

3. Query Parameter Versioning

// ✅ ACCEPTABLE: Version as query param
// /api/users?version=1

app.get('/api/users', (req, res) => {
  const version = parseInt(req.query.version) || LATEST_VERSION;
  // ...
});

Pros: Simple Cons: Optional parameter often forgotten

Correct Version Evolution Pattern

// Version 1: Original API
interface UserV1 {
  id: string;
  name: string;       // Full name
  email: string;
}

// Version 2: Split name into parts (BREAKING!)
interface UserV2 {
  id: string;
  firstName: string;  // New field
  lastName: string;   // New field
  email: string;
}

// ✅ CORRECT: Support both versions
class UserController {
  async getUserV1(id: string): Promise<UserV1> {
    const user = await this.userService.getUser(id);
    return {
      id: user.id,
      name: `${user.firstName} ${user.lastName}`,  // Compute for v1 clients
      email: user.email,
    };
  }

  async getUserV2(id: string): Promise<UserV2> {
    const user = await this.userService.getUser(id);
    return {
      id: user.id,
      firstName: user.firstName,
      lastName: user.lastName,
      email: user.email,
    };
  }
}

// ❌ WRONG: Silently change v1 response
// ❌ WRONG: Force all clients to update simultaneously
// ❌ WRONG: Remove v1 without deprecation period

Deprecation Protocol

Never surprise clients. Follow this:

// 1. Announce deprecation (headers + docs)
res.setHeader('Deprecation', 'true');
res.setHeader('Sunset', 'Sat, 01 Jan 2025 00:00:00 GMT');
res.setHeader('Link', '</api/v2/users>; rel="successor-version"');

// 2. Log usage to track migration
logger.info('Deprecated v1 endpoint called', { 
  endpoint: '/api/v1/users',
  clientId: req.clientId,
});

// 3. Maintain for deprecation period (minimum 6 months for external APIs)

// 4. Return 410 Gone after sunset date
if (isPastSunset('/api/v1/users')) {
  return res.status(410).json({
    error: 'This API version has been retired',
    migration: 'https://docs.api.com/migration-v1-to-v2',
    successor: '/api/v2/users',
  });
}

Pressure Resistance Protocol

1. "Just Ship It, We'll Version Later"

Pressure: "We need to launch, versioning can wait"

Response: Adding versioning to an existing API is 10x harder than starting with it. Clients already depend on the unversioned endpoints.

Action: Add /v1/ prefix now. Takes 5 minutes.

2. "It's Internal, We Control All Clients"

Pressure: "We can just update all our services"

Response: Internal APIs become external. Services can't update simultaneously. Deployments fail mid-rollout.

Action: Version internal APIs too. Your future self will thank you.

3. "It's a Bug Fix, Not a Breaking Change"

Pressure: "The old behavior was wrong"

Response: Cli

...