Versioning and Backward Compatibility

Versioning is a contract — a key part of any API design strategy. When you release version 2.0, you're promising something changed. When you release 1.1, you're promising it's compatible. When you release 1.0.1, you're promising only bugs got fixed. Get this wrong and consumers break silently or upgrade and everything stops working.

Backward compatibility is about respecting your consumers. You have control over your code. Your consumers don't. If you make a breaking change without warning, they're stuck. Either they maintain two integration paths or they can't upgrade. Backward compatibility gives them the power to upgrade on their schedule.

Why This Matters

Breaking changes are expensive. If your API is used by ten internal teams, a breaking change means ten teams coordinate. If it's public, it might break thousands of consumers. You don't even know who they are.

Deprecation strategies give consumers time. You want to remove an API endpoint? Don't remove it. Deprecate it. Tell consumers it's going away in six months. They have time to migrate. They don't scramble.

Clear versioning prevents confusion. If you always follow semantic versioning, consumers know what to expect. If you're inconsistent, they don't know whether to test thoroughly or assume compatibility.

Smooth upgrades keep your software current. If upgrading is painful, consumers use old versions longer. They miss security fixes. They miss improvements. Good versioning makes upgrading easy.

Semantic Versioning

Semantic versioning has three numbers: MAJOR.MINOR.PATCH.

MAJOR version increments when you make incompatible API changes. If 1.0.0 and 2.0.0 have different behavior or remove features, users upgrading from 1 to 2 might have breaking changes.

Example: removing an endpoint, changing a parameter type, changing return value structure.

MINOR version increments when you add functionality in a backward-compatible way. Code written for 1.0.0 works with 1.1.0. You added new features, but nothing changed in existing features.

Example: adding a new optional parameter, adding a new endpoint, adding a new feature behind a flag.

PATCH version increments when you fix bugs. No new features, no breaking changes. Just fixes.

Example: fixing incorrect calculations, fixing edge case handling, fixing security bugs.

1.0.0 - first release
1.0.1 - bug fix (patch)
1.1.0 - new feature added (minor)
1.1.1 - bug fix (patch)
2.0.0 - breaking changes (major)

The key principle: if a consumer could write code against 1.x.x and have it work in 1.y.y, then it's a minor version change. If they need to modify code, it's a major version change.

API Versioning Strategies

Semantic versioning tells you what changed. You still need to decide how to support multiple versions.

URL path versioning puts the version in the endpoint:

/api/v1/users
/api/v2/users

Advantages: clear and easy to route. Disadvantages: doubles endpoints, harder to migrate.

Header versioning puts the version in a header:

GET /api/users
Accept-Version: 1.0

Advantages: keeps URLs clean. Disadvantages: not cacheable via URL, requires client knowledge.

Content negotiation uses media types:

GET /api/users
Accept: application/vnd.myapi.v1+json

Advantages: technically pure. Disadvantages: complex, rarely used outside RESTful APIs.

Query parameter versioning puts the version in a query param:

GET /api/users?version=1

Advantages: simple. Disadvantages: less standard, harder to enforce.

Most teams use URL path versioning. It's clear and easy to understand.

Maintaining Backward Compatibility

The goal is to support multiple versions without duplicating logic. Here's the pattern:

Core logic is version-agnostic. The business logic for "get a user" is the same regardless of version. The difference is in the API contract—what fields are returned, what fields are required.

// Core logic - version agnostic
async function getUser(userId) {
  const user = await database.query('SELECT * FROM users WHERE id = $1', [userId]);
  if (!user) throw new NotFoundError();
  return user;
}

// v1 endpoint - returns all fields
router.get('/api/v1/users/:id', async (req, res) => {
  const user = await getUser(req.params.id);
  res.json({
    id: user.id,
    name: user.name,
    email: user.email,
    created_at: user.created_at
  });
});

// v2 endpoint - returns more fields
router.get('/api/v2/users/:id', async (req, res) => {
  const user = await getUser(req.params.id);
  res.json({
    id: user.id,
    name: user.name,
    email: user.email,
    phone: user.phone,
    created_at: user.created_at,
    updated_at: user.updated_at,
    status: user.status
  });
});

The core logic is the same. The endpoint format is different. This is much simpler than duplicating the entire function.

Transform layers convert between versions. If the data format changes significantly, a transform layer handles it.

function transformUserToV1(user) {
  return {
    id: user.id,
    name: user.name,
    email: user.email
  };
}

function transformUserToV2(user) {
  return {
    id: user.id,
    name: user.name,
    email: user.email,
    phone: user.phone,
    status: user.status
  };
}

Feature flags let you change behavior without versioning. If you're changing how something works and want to give consumers time to adapt, use a flag.

router.get('/api/users/:id', async (req, res) => {
  const user = await getUser(req.params.id);

  if (flags.isEnabled('new_user_format_v2', req.headers['client-id'])) {
    res.json(transformUserToV2(user));
  } else {
    res.json(transformUserToV1(user));
  }
});

Deprecation Strategies

You want to remove something. Don't just remove it. Deprecate it.

Year 1: Announce deprecation. Release a new version that includes the replacement. Document that the old API is deprecated. Tell consumers: "This will go away in [date]."

## Deprecation Notice
The GET /api/v1/users endpoint is deprecated as of v2.0 and will be removed on 2027-01-01.
Use GET /api/v2/users instead. See migration guide at [link].

Year 2: Keep supporting it. Continue supporting the old API, but actively encourage migration. Maybe send warnings in responses.

res.header('Deprecation', 'true');
res.header('Sunset', 'Sun, 01 Jan 2027 00:00:00 GMT');

Year 3: Remove it. You've given consumers a year and a half. Remove the old API.

The timeline depends on your consumer base. Internal APIs might move faster. Public APIs should move slower.

Schema Evolution

For databases and data structures, schema evolution is critical. You can't force consumers to migrate schemas instantly. You need to support old and new schemas together.

Add fields as optional. Don't require new fields. Make them optional, provide defaults.

ALTER TABLE users ADD COLUMN phone VARCHAR(20) DEFAULT NULL;

Code can write phone if it wants. Code doesn't have to.

Support old and new field names. If you rename a field, support both names temporarily.

function createUser(data) {
  // Support both email and mail_address during transition
  const email = data.email || data.mail_address;
  if (!email) throw new ValidationError('email required');

  return database.insert({
    email: email,
    mail_address: email // support both for now
  });
}

Default values for missing fields. If you remove a field, provide a default when reading old data.

function getUser(userId) {
  const user = database.query(...);
  return {
    ...user,
    status: user.status || 'active' // default for old records
  };
}

Versioning in AI-Assisted Development

When agents generate code and need to integrate with versioned APIs, clear versioning helps them understand what's stable and what's in flux.

Agents can also help maintain compatibility. They can update consumers when you deprecate an API. They can generate migration guides. They can test whether code works across versions.

FAQ

describe('Backward compatibility', () => {
  it('v1 API is still accessible', async () => {
    const response = await fetch('/api/v1/users/123');
    expect(response.status).toBe(200);
  });
});

Primary Sources

• Tom Preston-Werner's semantic versioning standard for version numbering clarity. Semantic Versioning
• Martin Fowler's patterns for enterprise application compatibility and versioning. EAA Patterns
• Google's engineering practices on API versioning and backward compatibility. Google Eng Practices
• The Pragmatic Programmer's approach to managing API versions and deprecation. Pragmatic Programmer
• Steve McConnell's guide to designing maintainable APIs and version strategies. Code Complete
• Robert Martin's handbook on writing stable, backward-compatible code. Clean Code
• John Ousterhout's philosophy on designing stable, extensible interfaces. Philosophy of Design