When to Version: Breaking vs Additive Changes

The first decision: does this change require a new version? Many changes don't. Additive changes (new endpoints, new optional fields, new query parameters) are backward compatible—old clients ignore what they don't understand. Breaking changes (removing fields, changing types, altering semantics) require new versions because old clients will break.

The key insight: version numbers should represent compatibility contracts, not release cadence. If every deployment increments the version, you haven't created versions—you've created a deployment log. Versions should communicate: "this change breaks the contract, clients must update."

Breaking Changes

// Breaking: Removing a field
// v1 response
{
  "id": "123",
  "name": "John Doe",
  "email": "[email protected]"
}

// v2 response (removed "email")
{
  "id": "123",
  "name": "John Doe"
}
// Old clients expecting "email" will break

// Breaking: Changing field type
// v1 response
{
  "price": 29.99
}

// v2 response (changed to object)
{
  "price": {
    "amount": 29.99,
    "currency": "USD"
  }
}
// Old clients treating price as number will break

// Breaking: Renaming field
// v1: "userName"
// v2: "username"
// Field name changed, old clients break

// Breaking: Changing semantics
// v1: DELETE /users/123 (soft delete)
// v2: DELETE /users/123 (hard delete)
// Same endpoint, different behavior—breaks assumptions

Additive Changes (No Version Bump)

// Safe: Adding new field
// v1 response
{
  "id": "123",
  "email": "[email protected]"
}

// v1 response with new field (no version change)
{
  "id": "123",
  "email": "[email protected]",
  "phoneNumber": "+1234567890"  // Old clients ignore this
}

// Safe: Adding new endpoint
POST /v1/users          (existing)
GET /v1/users/export    (new endpoint, doesn't affect existing)

// Safe: Adding new optional parameter
GET /v1/products?category=electronics              (existing)
GET /v1/products?category=electronics&minPrice=100 (minPrice is new, optional)

// Safe: Making required field optional
// v1: email required
// Later: email optional (still accepted, just not required)
// Old clients still work

Versioning Mechanisms: URL vs Header vs Content Type

Three primary ways to indicate API version: in the URL path, in a custom header, or in the Accept/Content-Type header (content negotiation). Each has trade-offs.

URL Path Versioning

GET /v1/users/123
GET /v2/users/123
GET /v3/users/123

// Routing in Express
app.use('/v1', v1Routes);
app.use('/v2', v2Routes);
app.use('/v3', v3Routes);

Pros: Explicit and visible. Easy to test in browser. Clear in logs and monitoring. Simple routing. Clients can pin to specific versions easily.

Cons: URLs change between versions, which feels wrong for "same resource." Complicates caching (different URLs for same resource). Not strictly RESTful (versions aren't resources).

Best for: Public APIs, APIs with long support windows, teams that value explicitness over REST purity.

Custom Header Versioning

GET /users/123
API-Version: 2

// Or
X-API-Version: 2

// Server reads header to determine version
app.use((req, res, next) => {
  const version = req.headers['api-version'] || '1';
  req.apiVersion = version;
  next();
});

Pros: URLs remain stable. RESTful—same resource, different representations. Clean URL structure.

Cons: Less visible (headers hidden in tools). Harder to test in browser. Requires custom header support in HTTP libraries. Easier to forget version header.

Best for: Internal APIs, APIs where URL stability matters, teams comfortable with header-based versioning.

Content Negotiation (Accept Header)

GET /users/123
Accept: application/vnd.myapi.v2+json

// Response
Content-Type: application/vnd.myapi.v2+json
{ "id": "123", ... }

// Server parses Accept header
app.use((req, res, next) => {
  const accept = req.headers.accept || '';
  const match = accept.match(/vnd\.myapi\.v(\d+)/);
  const version = match ? match[1] : '1';
  req.apiVersion = version;
  next();
});

Pros: Most RESTful—uses HTTP content negotiation as designed. URLs stable. Clients explicitly declare what format they understand.

Cons: Complex to implement correctly. Harder to test. Non-obvious to developers unfamiliar with content negotiation. Verbose accept headers.

Best for: APIs built by teams committed to REST principles, APIs where content type negotiation is already used (XML vs JSON).

Implementation Pattern: Shared Logic, Versioned Adapters

The common mistake: duplicating the entire codebase per version. You end up with /v1 and /v2 directories containing nearly identical code. Fixing a bug requires changing multiple versions. This doesn't scale beyond 2-3 versions.

Better approach: share domain logic across versions, version only the API layer (request/response transformations).

Architecture

src/
├── domain/              # Shared business logic (version-independent)
│   ├── services/
│   │   └── UserService.js
│   └── models/
│       └── User.js
│
├── api/
│   ├── v1/              # Version 1 API layer
│   │   ├── routes/
│   │   │   └── users.js
│   │   ├── controllers/
│   │   │   └── UserController.js
│   │   └── serializers/
│   │       └── UserSerializer.js
│   │
│   └── v2/              # Version 2 API layer
│       ├── routes/
│       │   └── users.js
│       ├── controllers/
│       │   └── UserController.js
│       └── serializers/
│           └── UserSerializer.js
│
└── main.js

Shared Domain Logic

// src/domain/services/UserService.js
// Version-independent business logic

class UserService {
  constructor(userRepository) {
    this.userRepository = userRepository;
  }

  async getUser(id) {
    const user = await this.userRepository.findById(id);
    if (!user) throw new Error('User not found');
    return user;
  }

  async createUser(data) {
    // Business logic: validation, password hashing, etc.
    const user = await this.userRepository.create(data);
    return user;
  }
}

module.exports = UserService;

Version-Specific Serializers

// src/api/v1/serializers/UserSerializer.js
class UserSerializerV1 {
  serialize(user) {
    return {
      id: user.id,
      name: user.name,          // v1 has single "name" field
      email: user.email,
      createdAt: user.createdAt
    };
  }
}

// src/api/v2/serializers/UserSerializer.js
class UserSerializerV2 {
  serialize(user) {
    return {
      id: user.id,
      firstName: user.firstName,  // v2 split name into firstName/lastName
      lastName: user.lastName,
      email: user.email,
      phoneNumber: user.phoneNumber,  // v2 added phone
      createdAt: user.createdAt.toISOString()  // v2 uses ISO format
    };
  }
}

module.exports = UserSerializerV2;

Version-Specific Controllers

// src/api/v1/controllers/UserController.js
const UserSerializerV1 = require('../serializers/UserSerializer');

class UserControllerV1 {
  constructor(userService) {
    this.userService = userService;
    this.serializer = new UserSerializerV1();
  }

  async getUser(req, res) {
    try {
      const user = await this.userService.getUser(req.params.id);
      res.json(this.serializer.serialize(user));
    } catch (error) {
      res.status(404).json({ error: error.message });
    }
  }
}

// src/api/v2/controllers/UserController.js
const UserSerializerV2 = require('../serializers/UserSerializer');

class UserControllerV2 {
  constructor(userService) {
    this.userService = userService;
    this.serializer = new UserSerializerV2();
  }

  async getUser(req, res) {
    try {
      const user = await this.userService.getUser(req.params.id);
      res.json(this.serializer.serialize(user));
    } catch (error) {
      // v2 uses different error format
      res.status(404).json({
        error: {
          code: 'USER_NOT_FOUND',
          message: error.message
        }
      });
    }
  }
}

module.exports = UserControllerV2;

Now business logic is shared. When you fix a bug in UserService, all versions benefit. Only the API layer (serialization, error handling) is versioned.

Database Schema Evolution Across Versions

The challenge: multiple API versions accessing the same database. v1 expects a "name" field, v2 expects "firstName" and "lastName". How do you evolve the schema without breaking old versions?

Strategy 1: Expand-Contract Pattern

Three phases: expand schema to support both old and new, migrate code to use new, contract schema by removing old.

// Phase 1: Expand (add new fields, keep old)
ALTER TABLE users ADD COLUMN first_name VARCHAR(255);
ALTER TABLE users ADD COLUMN last_name VARCHAR(255);
// Keep "name" column

// Application layer supports both
// v1 API: reads/writes "name"
// v2 API: reads/writes "firstName" and "lastName"
// Write to both during transition

// Phase 2: Migrate (update all rows)
UPDATE users SET
  first_name = SPLIT_PART(name, ' ', 1),
  last_name = SPLIT_PART(name, ' ', 2)
WHERE first_name IS NULL;

// Phase 3: Contract (remove old field after all clients migrated to v2)
// Deprecate v1 API
// After deprecation period, remove v1 support
ALTER TABLE users DROP COLUMN name;

Strategy 2: Database Views Per Version

Create views that present different schemas to different API versions.

// Underlying table (v2 schema)
CREATE TABLE users (
  id UUID PRIMARY KEY,
  first_name VARCHAR(255),
  last_name VARCHAR(255),
  email VARCHAR(255)
);

// View for v1 API (combines firstName and lastName into name)
CREATE VIEW users_v1 AS
SELECT
  id,
  first_name || ' ' || last_name AS name,
  email
FROM users;

// v1 API queries users_v1 view
// v2 API queries users table directly

This keeps schema changes isolated from API code but adds complexity for writes (triggers or application logic to keep views in sync).

Strategy 3: Transformation Layer

Store data in latest format, transform on read for old versions.

// Database uses v2 schema
// Repository layer transforms for different versions

class UserRepository {
  async findById(id, version = 'v2') {
    const row = await db.query('SELECT * FROM users WHERE id = $1', [id]);

    if (version === 'v1') {
      return this.transformToV1(row);
    }

    return row;
  }

  transformToV1(user) {
    return {
      id: user.id,
      name: `${user.first_name} ${user.last_name}`,
      email: user.email
    };
  }
}

Deprecation Strategy

Deprecating API versions is as important as releasing them. You can't support every version forever—maintenance cost grows linearly with supported versions.

Deprecation Timeline

// Month 0: Release v2, announce v1 deprecation
// Response headers communicate deprecation
HTTP/1.1 200 OK
Deprecation: true
Sunset: Wed, 01 Jan 2027 00:00:00 GMT
Link: ; rel="deprecation"

// Month 3: Warning logs for v1 usage
// Log every v1 request with client identifier
// Contact heavy users to coordinate migration

// Month 6: Rate limit v1 more aggressively
// Reduce rate limits to encourage migration
// Maintain generous limits for clients coordinating migration

// Month 9: v1 enters end-of-life
// Critical security fixes only, no new features
// Documentation marked as deprecated

// Month 12: v1 shutdown
// Return 410 Gone for v1 requests
HTTP/1.1 410 Gone
Content-Type: application/json
{
  "error": {
    "code": "API_VERSION_RETIRED",
    "message": "API v1 has been retired. Please upgrade to v2.",
    "migrationGuide": "https://api.example.com/docs/migration-v1-to-v2",
    "supportedVersions": ["v2", "v3"]
  }
}

Communication Strategy

• Announce deprecation at least 12 months before shutdown for public APIs, 6 months for internal APIs
• Document migration guide with code examples showing changes
• Provide sunset date in HTTP headers (Sunset header, RFC 8594)
• Email registered API users with timeline and migration resources
• Monitor version usage to identify clients still on old versions
• Offer migration support for large customers

// Example migration guide structure
Migration from v1 to v2

Breaking Changes:
1. User name field split
   - v1: { "name": "John Doe" }
   - v2: { "firstName": "John", "lastName": "Doe" }

2. Date format changed to ISO 8601
   - v1: "2026-03-28"
   - v2: "2026-03-28T10:30:00Z"

3. Error response structure changed
   - v1: { "error": "User not found" }
   - v2: { "error": { "code": "USER_NOT_FOUND", "message": "..." }}

New Features in v2:
- Phone number field added
- Batch operations endpoint: POST /users/batch
- Cursor-based pagination replaces offset

Code Examples:
[Before and after code showing how to update client code]

Semantic Versioning for APIs

Semantic versioning (semver) for APIs adapts traditional semver (MAJOR.MINOR.PATCH) to API contracts.

Version Number Semantics

// MAJOR version: breaking changes
v1 → v2: Removed field, changed type, altered semantics

// MINOR version: backward-compatible additions
v2.0 → v2.1: Added new endpoint, added optional field

// PATCH version: bug fixes, no API contract changes
v2.1.0 → v2.1.1: Fixed bug in validation logic, no contract change

Many APIs simplify this to major versions only (v1, v2, v3) since minor/patch versions don't require client changes anyway. Clients can safely ignore minor/patch increments.

Version Compatibility Testing

Use contract testing to verify backward compatibility automatically.

// Example with Pact (contract testing library)
describe('User API v1 contract', () => {
  it('GET /users/:id returns expected structure', async () => {
    const response = await request(app)
      .get('/v1/users/123');

    expect(response.body).toMatchObject({
      id: expect.any(String),
      name: expect.any(String),
      email: expect.any(String),
      createdAt: expect.any(String)
    });
  });
});

describe('User API v2 contract', () => {
  it('GET /users/:id returns expected structure', async () => {
    const response = await request(app)
      .get('/v2/users/123');

    expect(response.body).toMatchObject({
      id: expect.any(String),
      firstName: expect.any(String),
      lastName: expect.any(String),
      email: expect.any(String),
      phoneNumber: expect.any(String),
      createdAt: expect.any(String)
    });
  });
});

Run these tests in CI to catch accidental breaking changes. If v1 contract tests fail, you know you've accidentally broken backward compatibility.

Special Cases and Edge Cases

Versioning Webhooks

Webhooks pose a challenge: you push data to clients, they don't request it. Version webhooks by allowing clients to specify desired version when registering.

// Webhook registration
POST /webhooks
{
  "url": "https://client.com/webhook",
  "events": ["user.created", "user.updated"],
  "version": "v2"  // Client specifies version
}

// When sending webhook, use registered version
async function sendWebhook(webhook, event) {
  const payload = serializeEvent(event, webhook.version);

  await fetch(webhook.url, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Webhook-Version': webhook.version
    },
    body: JSON.stringify(payload)
  });
}

Versioning Background Jobs

Background jobs that serialize data may need version awareness.

// Include version in job metadata
await queue.enqueue('send-email', {
  userId: '123',
  emailType: 'welcome',
  apiVersion: 'v2'  // Record version at job creation
});

// Worker uses recorded version
async function processEmailJob(job) {
  const user = await userService.getUser(job.userId, job.apiVersion);
  await emailService.send(user, job.emailType);
}

Versioning GraphQL APIs

GraphQL has built-in evolution support through field deprecation. Versioning is less common—instead, deprecate fields and add new ones.

type User {
  id: ID!
  name: String @deprecated(reason: "Use firstName and lastName instead")
  firstName: String
  lastName: String
  email: String
}

# Clients can query deprecated fields during migration
query {
  user(id: "123") {
    id
    name  # Still works, returns warning
    firstName
    lastName
  }
}

Organizational Aspects

Version Ownership

Clarify who owns each version. In large teams, different teams may maintain different versions during migration periods. Make ownership explicit.

API Version Support Matrix
--------------------------
v1: Deprecated (end-of-life: 2027-01-01)
    Owner: Legacy API Team
    Support level: Critical bugs only

v2: Stable (current recommended version)
    Owner: API Platform Team
    Support level: Full support, new features

v3: Beta (preview for early adopters)
    Owner: API Platform Team
    Support level: Best effort, may have breaking changes

Feature Development Across Versions

When supporting multiple versions, decide where new features land. Usually: new features go in latest version only. Backporting to old versions is exceptional.

Decision Matrix for Feature Backporting
---------------------------------------
Backport to previous version if:
- Critical security fix
- Data corruption bug
- Major customer-requested feature with business justification

Do NOT backport if:
- Nice-to-have feature
- Performance improvement (unless critical)
- Refactoring or code quality improvement

Frequently Asked Questions

Should I version from v1 or v0?

Start with v1 for production APIs. v0 signals "not ready for production, expect breaking changes." Only use v0 for experimental APIs during development. Once you commit to stability, jump to v1. There's no value in a v0 that's actually stable—it just confuses users about whether the API is production-ready.

How many versions should I support simultaneously?

Two is common: current stable version and previous version during deprecation. Supporting three or more versions creates significant maintenance burden. Plan deprecation timelines that allow moving to N and N-1 support, depreciating N-2 within 12-18 months of releasing N.

Can I use date-based versioning like 2024-03-28?

Some APIs (Stripe, GitHub) use date-based versions. This works well when you make frequent, small breaking changes rather than major version bumps. Clients pin to a specific date version, new clients get the latest. Trade-off: harder to understand compatibility at a glance compared to semantic versions. Best for platform APIs with many small iterations.

How do I handle versioning in microservices?

Each service can version independently or you can version at the API gateway level. Independent versioning gives flexibility but creates complexity (service A v2 + service B v3 = ?). Gateway-level versioning (v1 routes to specific service versions) is simpler but requires coordinated releases. Choose based on team structure and deployment model.

Should internal APIs use versioning?

It depends on coupling. If the API and all its clients are deployed together (monorepo, same release cycle), versioning adds little value—just coordinate breaking changes. If clients and API deploy independently (different teams, different cadences), version the API to enable independent evolution. Internal doesn't mean "no versioning needed," it means "consider deployment model."

How do I version file upload/download formats?

Include version in the file format or metadata. For JSON/XML, add a version field. For binary formats, include a version header. This lets you evolve file formats independently of API versions. Client specifies accepted versions in Accept header or query parameter.

What's the difference between API versioning and feature flags?

API versions are about compatibility contracts—major structural changes that require client updates. Feature flags control behavior within a version—gradual rollouts, A/B tests, kill switches. Use versions for breaking changes, feature flags for incremental changes within a version. They're complementary strategies.

How do I handle versioning in SDK/client libraries?

SDK versions can be independent of API versions. SDK v2.0 might support API v1 and v2. Document which SDK versions support which API versions. Deprecate SDK versions alongside API versions—when you sunset API v1, deprecate SDK versions that only support v1.

Should I version authentication mechanisms separately?

Generally no—bundle auth changes with API versions. If you change from API keys to OAuth 2.0, that's a major version bump. Exception: supporting multiple auth methods simultaneously (API key OR OAuth) doesn't require versioning, it's just different auth flows. Version when removing auth support, not when adding.

How do I test version compatibility in CI/CD?

Maintain contract tests for each supported version. Run them on every build. Use snapshot testing to catch unintentional response format changes. Consider running old client integration tests against new API versions to verify backward compatibility. Failed contract tests block deployment.

Conclusion

API versioning succeeds when it balances evolution and stability. Version numbers should represent compatibility contracts—increment major versions for breaking changes, use minor versions (or no version bump) for additive changes. Choose a versioning mechanism (URL, header, or content type) and apply it consistently. Share business logic across versions while versioning only the API layer to minimize code duplication.

Design APIs with evolution in mind from the start: clients ignore unknown fields, servers accept them gracefully, additive changes don't break old clients. When breaking changes are necessary, plan migrations carefully with clear timelines, migration guides, and sunset dates. Support at most two versions simultaneously—current and previous during deprecation—to keep maintenance costs sustainable.

The goal is enabling API evolution without breaking client integrations. Good versioning strategies make this possible by providing stability guarantees (v1 won't change), migration paths (v1 to v2 guide), and clear communication (deprecation timelines). Start versioning from v1, increment deliberately for breaking changes, and sunset old versions on predictable schedules. This discipline keeps APIs maintainable while supporting client needs for stability and predictability.