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: Clients may depend on the "wrong" behavior. A fix can break them.

Action: Fix in new version. Document the fix. Let clients opt-in.

4. "Nobody Uses That Field"

Pressure: "Analytics show it's unused"

Response: Analytics might be wrong. One client relying on it = breaking change.

Action: Deprecate with warning, keep returning the field, sunset after migration period.

5. "We'll Just Notify Clients"

Pressure: "We'll email everyone before the change"

Response: Emails get missed. Clients need deploy time. Surprise breaks cause outages.

Action: Deprecation headers + sunset period + new version.

Red Flags - STOP and Reconsider

If you notice ANY of these, you're about to break clients:

• Removing or renaming fields without new version
• Changing response structure "to improve it"
• "Nobody will notice this change"
• No version in API path or headers
• Only one version supported
• Deprecating without sunset date
• Changing semantics (same field, different meaning)

All of these mean: Create a new API version.

Version Lifecycle Management

┌─────────┐     ┌─────────────┐     ┌────────────┐     ┌───────┐
│  Alpha  │ ──► │  Released   │ ──► │ Deprecated │ ──► │ Sunset│
└─────────┘     └─────────────┘     └────────────┘     └───────┘
 Breaking OK     No breaking         Warn clients      410 Gone
                 Support 2-3 ver     6+ months         Remove code

Common Rationalizations (All Invalid)

Quick Reference

The Bottom Line

Version from day one. Never break released versions. Deprecate gracefully.

When pressured to "just change it" or "version later": add versioning now, create new version for breaking changes, give clients time to migrate. API stability is a contract—don't break it.