API Versioning: Managing Change Without Breaking Clients

APIs change. You add features, rename fields, split resources, and sometimes fix mistakes. The challenge is making these changes without breaking existing clients.

Versioning gives you a way to introduce changes while maintaining backward compatibility with older clients.

The RESTful API Design post covers REST basics. This post focuses on versioning strategies.

---

Introduction

APIs serve multiple clients simultaneously. A mobile app from 6 months ago still needs to work. Web clients deployed last week need to work. New clients can use new features.

Without versioning, a breaking change affects all clients at once. With versioning, you introduce changes in a new version while keeping the old version running temporarily.

graph LR
    A[Old Client] -->|Uses v1| B[API v1]
    C[New Client] -->|Uses v2| D[API v2]
    D --> E[New Features]
    B --> F[Stable Old API]

---

Core Concepts

Three approaches exist for API versioning.

URL Path Versioning

The version appears in the URL path:

GET /v1/users
GET /v2/users
POST /v1/users
POST /v2/users

This is the most common approach. It is explicit and easy to test.

URL path versioning is explicit and easy to test. Load balancers route by URL prefix, and different versions cache separately. The downside is the version appears in every endpoint, and some argue it violates REST principles about resource URLs staying stable.

Header Versioning

The version appears in a request header:

GET /users
Accept: application/vnd.example.v2+json

GET /users
API-Version: 2023-01-01

Header versioning keeps URLs clean and supports content negotiation. The trade-offs are that the version is less visible, testing requires header setup, and caching gets complicated when the same URL returns different results based on headers.

Query Parameter Versioning

The version appears as a query parameter:

GET /users?version=2
GET /users?v=2

Query parameter versioning keeps URLs readable and is easy to add and test. The downside is that parameters can get lost in logs, proxies sometimes strip query params, and it is less explicit than URL versioning.

---

URL Path Versioning in Practice

Most companies use URL path versioning. It is the simplest to implement and understand.

# Structure
/v{version}/{resource}
/v1/users
/v2/users
/v3/orders

# Full examples
GET /v1/users/123
POST /v2/orders
PUT /v3/products/456

Routing Implementation

// Express.js routing with versioning
app.use("/v1", require("./routes/v1"));
app.use("/v2", require("./routes/v2"));
app.use("/v3", require("./routes/v3"));

API Gateway

# API Gateway routing
- path: /v1/*
  target: backend-v1
- path: /v2/*
  target: backend-v2
- path: /v3/*
  target: backend-v3

---

Backward Compatibility & Lifecycle

Versioning is not a license to make breaking changes. Try to stay backward compatible within a version.

What Breaks Clients

These changes break existing clients:

• Removing fields from responses
• Changing field types
• Renaming fields
• Changing field meaning
• Changing authentication requirements
• Changing required parameters

What Does Not Break Clients

These changes are backward compatible:

• Adding new optional fields to responses
• Adding new optional parameters to requests
• Adding new endpoints
• Reordering fields in responses (if clients do not depend on order)

Deprecation Practices

When you must make breaking changes:

1. Announce deprecation in documentation
2. Add deprecation headers in responses
3. Support old version for a transition period (typically 6-12 months)
4. Monitor usage of old versions
5. Sunset the old version

# Deprecation response header
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Dec 2026 23:59:59 GMT
Link: <https://api.example.com/v2/users>; rel="successor-version"

---

Version Lifecycle

A typical version lifecycle:

graph LR
    A[Introduce v1] --> B[Monitor Usage]
    B --> C[v2 Released]
    C --> D[v1 Deprecated]
    D --> E[v1 Usage Low]
    E --> F[v1 Sunset]
    F --> G[v1 Removed]

Timeline Example

Phase	Duration	Notes
New version introduced	-	Both v1 and v2 available
Old version deprecated	6 months	Deprecation header added
Old version sunset announced	3 months	Usage monitored
Old version sunset	-	Still available at reduced SLA
Old version removed	-	Only new version remains

---

SDK Versioning Patterns

Client SDKs face unique versioning challenges. They wrap your API and expose it to developers who consume it in their applications. How the SDK handles versions directly impacts the developer experience.

Semantic Versioning in SDKs

// npm package versioning following semver
// package.json
{
  "dependencies": {
    "api-client": "^2.3.0"  // ^ = compatible with 2.x.x
  }
}

// Breaking changes bump major version (2 -> 3)
// New features bump minor version (2.3 -> 2.4)
// Bug fixes bump patch version (2.3.0 -> 2.3.1)

SDK Version Skew

When client applications use different SDK versions simultaneously:

graph TD
    A[Client App v2.1] -->|SDK v2.1| B[API v2]
    C[Client App v1.5] -->|SDK v1.5| D[API v1]
    E[New Client] -->|SDK v3.0| F[API v3]
    B --> G[All v2 endpoints]
    D --> H[v1 endpoints only]
    F --> I[v3 new features]

Feature Flags for Gradual Migration

// SDK configuration with feature flags
const client = new ApiClient({
  version: "v2",
  features: {
    newResponseFormat: true, // Gradual rollout
    bulkOperations: false, // Disabled until ready
  },
});

// Server-side feature detection
if (clientFeatures.newResponseFormat) {
  return formatV2Response(data);
}

Deprecation Warnings in SDK

// SDK deprecation warning
class UsersClient {
  getUser(id) {
    console.warn(
      "[DEPRECATED] getUser() will be removed in v3. " +
        "Use getUserById() instead. See: https://api.dev/docs/migration",
    );
    return this.getUserById(id);
  }
}

SDK Release Cadence

SDK Version	API Versions	Support Duration	Migration Path
SDK v1.x	API v1	18 months	→ v2.x
SDK v2.x	API v1, v2	24 months	→ v3.x
SDK v3.x	API v2, v3	Active	Current

---

Advanced Content Negotiation

Header versioning uses content negotiation mechanisms defined in HTTP. Understanding these nuances helps you design more flexible APIs.

Media Type Versioning

# Request with media type versioning
GET /users HTTP/1.1
Host: api.example.com
Accept: application/vnd.example.v2+json

# Response
HTTP/1.1 200 OK
Content-Type: application/vnd.example.v2+json

Vendor-Specific Media Types

// Express.js handling vendor media types
app.get("/users", (req, res) => {
  const acceptHeader = req.get("Accept");

  if (acceptHeader.includes("application/vnd.example.v2+json")) {
    return res.json(formatV2(users));
  }
  if (acceptHeader.includes("application/vnd.example.v1+json")) {
    return res.json(formatV1(users));
  }

  // Default to latest version
  res.json(formatV2(users));
});

Content Negotiation Complexity Trade-offs

Approach	Pros	Cons
Simple header	Easy to implement	Limited version expression
Vendor media type	Standard HTTP, type-safe	Complex routing logic
Date-based version	Reflects release date	Unclear API stability
Profile parameter	Extensible, standard	Additional parsing overhead
Custom header	Explicit, easy to read	Non-standard, proxy issues

---

Versioning Maturity Model

Teams evolve through stages when implementing API versioning. Understanding where you are helps identify next steps.

Maturity Levels

graph LR
    A[Level 0: No Versioning] --> B[Level 1: Basic Versioning]
    B --> C[Level 2: Structured Versioning]
    C --> D[Level 3: Advanced Practices]
    D --> E[Level 4: Optimized Lifecycle]

Level 0: No Versioning

Characteristics:

• No version in URL or headers
• Changes deployed directly to endpoints
• Breaking changes affect all clients immediately

Indicators:

• Frequent client breakages reported
• No deprecation timeline visible
• Developers afraid to make changes

Level 1: Basic Versioning

Characteristics:

• URL path versioning (/v1/, /v2/)
• Manual route splitting
• Basic deprecation notices

Indicators:

• Version appears in URLs
• Old versions run in parallel
• Simple monitoring exists

Level 2: Structured Versioning

Characteristics:

• Consistent versioning strategy
• Automated version routing
• Formal deprecation timelines
• Version usage monitoring

Indicators:

• API gateway handles routing
• Usage dashboards per version
• Public deprecation policy exists

Level 3: Advanced Practices

Characteristics:

• Multi-version coexistence with transformations
• Contract testing between versions
• SDK automated version detection
• Canary releases for version rollouts

Indicators:

• Schema transformation layers
• Automated compatibility tests
• SDK auto-upgrade recommendations

Level 4: Optimized Lifecycle

Characteristics:

• Version usage triggers automated sunset workflows
• A/B testing between versions
• Feature flags for gradual rollouts
• Developer experience metrics tracked

Indicators:

• ML-based version migration predictions
• < 1% traffic triggers sunset review
• Developer satisfaction scores tracked

---

Contract Testing Strategies

Contract testing ensures that API versions remain compatible with their contracts and with each other. It prevents breaking changes from reaching production.

Consumer-Driven Contracts

// Consumer side contract test (using Pact)
const { Pact } = require("@pact-foundation/pact");

const provider = new Pact({
  consumer: "mobile-app",
  provider: "users-api",
});

describe("Users API contract", () => {
  it("returns user with id, name, email for v2", async () => {
    await provider.addInteraction({
      state: "user 123 exists",
      uponReceiving: "a request for user 123",
      withRequest: {
        method: "GET",
        path: "/v2/users/123",
        headers: { Accept: "application/json" },
      },
      willRespondWith: {
        status: 200,
        body: {
          id: 123,
          name: "Alice",
          email: "alice@example.com",
        },
      },
    });
  });
});

Version Compatibility Matrix

graph LR
    A[v1 Contract] -->|Test| B[v1 Server]
    A -->|Test| C[v2 Server]
    A -->|Test| D[v3 Server]
    B --> E[Pass]
    C --> E
    D --> E

Automated Contract Validation Pipeline

# CI pipeline for contract testing
stages:
  - contract:
      - Consumer: Run Pact tests against mock
      - Publish: Publish contract to broker

  - provider:
      - Fetch: Download contracts from broker
      - Verify: Run provider tests against all contracts
      - Report: Publish results to contract broker

  - gate:
      - Check: All contracts must pass
      - Block: Failing contracts block deployment

Contract Version Alignment

API Version	Contract Version	Schema Registry	Compatibility
v1	1.0.0	Avro/JSON Schema	Full
v2	2.0.0	OpenAPI 3.1	Full
v3	3.0.0	OpenAPI 3.1	Full

---

Client Migration Guide

Migrating clients between API versions is often the hardest part of versioning. Good migration guidance reduces support burden and prevents client breakages.

Migration Timeline

gantt
    title Client Migration Timeline
    dateFormat  YYYY-MM-DD
    section Analysis
    Identify breaking changes     :2026-01-01, 14d
    Assess client impact          :2026-01-15, 7d
    section Communication
    Deprecation announcement      :2026-01-22, 7d
    Migration documentation       :2026-01-29, 14d
    section Execution
    Old version available         :2026-02-12, 180d
    Migration support             :2026-02-12, 120d
    Old version sunset            :2026-08-10, 30d

Client-Side Migration Steps

1. Audit Current Usage

   // Log all v1 API calls to identify migration scope
   app.use("/v1/*", (req, res, next) => {
     logger.warn(`v1 endpoint called: ${req.path}`, {
       clientId: req.headers["x-client-id"],
       timestamp: new Date().toISOString(),
     });
     next();
   });

2. Provide Migration Checklist

   ## v1 to v2 Migration Checklist
   
   - [ ] Update endpoint URLs from /v1/ to /v2/
   - [ ] Add new required fields to requests
   - [ ] Handle new response field formats
   - [ ] Update authentication if changed
   - [ ] Test with v2 endpoint before production
   - [ ] Monitor for unexpected errors

3. Offer Transition Period Features

   // Dual-mode support during transition
   app.get("/v2/users/:id", (req, res) => {
     if (req.query.compatibility === "v1") {
       // Return v1-compatible format for clients still migrating
       return res.json(transformToV1Format(user));
     }
     return res.json(user);
   });

Migration Anti-Patterns to Avoid

Anti-Pattern	Why It Fails	Better Approach
Silent breaking changes	Clients fail without warning	Version bump + clear deprecation
One-week sunset notice	Clients cannot react in time	6-12 month transition period
No migration documentation	Clients stuck on old version	Comprehensive migration guide
Removing old version too fast	Mobile apps break	Monitor usage before removal
Forcing migration	Rushes clients, causes bugs	Incentivize, don’t force

---

Multi-Version Deployment

Running multiple versions simultaneously requires planning.

Shared Database

graph TD
    A[v1 Code] --> B[Shared Database]
    A2[v2 Code] --> B
    B --> C[Schema Migration]

Both versions use the same database. Schema changes must support both versions during transition.

Version-Specific Transformations

// Transform response based on version
function userResponse(user, version) {
  if (version === "v1") {
    return {
      id: user.id,
      name: user.full_name,
      email: user.email_address,
    };
  }
  return {
    id: user.id,
    name: user.name,
    email: user.email,
    preferences: user.preferences,
  };
}

---

Trade-off Analysis

Factor	URL Path Versioning	Header Versioning	Query Param Versioning
Visibility	High - visible in every URL	Low - hidden in headers	Medium - visible in URL
Testability	Easy - just change URL	Moderate - need header setup	Easy - just add param
Caching	Separate caches per version	Complex - same URL diff content	Complex - proxy issues
REST Compliance	Violates resource stability	Better - resources stay same	Neutral
Load Balancer	Easy - route by prefix	Harder - need header inspection	Moderate - strip params
Client Simplicity	Simple - version in URL	Complex - must set headers	Simple - just append param
URL Cleanliness	Cluttered with version	Clean URLs	Moderate
SEO Impact	Multiple URLs per resource	Single URL	Single URL
Default To	Most teams	Flexible APIs	Quick prototypes

When to Choose Each Strategy

Scenario	Recommended Strategy
Public API with many clients	URL Path Versioning
Internal API with known clients	Header Versioning
Quick iteration / MVP phase	Query Parameter Versioning
Microservices with API gateway	Header Versioning
Mobile apps with limited updates	URL Path Versioning
Browser-based SPAs	Header or URL Path

---

When to Version

Not every change requires a new version.

Version When

• Changing field names
• Changing field types
• Removing fields
• Changing authentication
• Changing required parameters
• Removing endpoints

Do Not Version When

• Adding new optional fields
• Adding new endpoints
• Adding new optional parameters
• Fixing bugs that were always wrong
• Performance improvements

---

Production Failure Scenarios

Failure	Impact	Mitigation
Breaking change without new version	Existing clients break	Never make breaking changes; always increment version
Old version sunset too soon	Client applications fail	Monitor usage before sunset; give adequate notice (6-12 months)
Version coexistence bugs	Data inconsistency between versions	Test all version combinations; use transformation layers
Shared database schema conflicts	Version N breaks if version N+1 changes schema	Use database abstraction; migrations must support all versions
Incorrect version routing	Wrong version serves request; wrong data	Implement routing tests; monitor version distribution
Missing deprecation headers	Clients do not know version is deprecated	Always include Deprecation and Sunset headers
Version proliferation	Too many versions to maintain	Set clear sunset policies; consolidate versions
Side-by-side deployment complexity	Operational overhead increases	Automate version deployment; use API gateway

---

Common Pitfalls / Anti-Patterns

Making Breaking Changes Within a Version

Never break existing clients within a version.

# Version 1.0 - Original
GET /v1/users/123
# Returns: { "id": 123, "name": "Alice", "email": "alice@example.com" }

# WRONG - Breaking change in v1
GET /v1/users/123
# Now returns: { "id": 123, "full_name": "Alice Smith" }
# Old clients cannot parse "full_name"

# CORRECT - New version for breaking change
GET /v2/users/123
# Returns: { "id": 123, "name": "Alice Smith", "email": "alice@example.com" }

Ignoring Deprecation Communication

Clients cannot adapt if they do not know a version is going away.

# Always include deprecation headers
HTTP/1.1 200 OK
Deprecation: true
Sunset: Sat, 31 Dec 2026 23:59:59 GMT
Link: <https://api.example.com/v2/users>; rel="successor-version"

Setting Sunset Dates Too Soon

Short deprecation periods cause client breakage.

# Bad: Too short notice
Deprecation: true
Sunset: Tue, 31 Mar 2026  # Only 1 week notice!

# Good: Reasonable transition period
Deprecation: true
Sunset: Sat, 31 Dec 2026  # 9 months notice

Not Monitoring Version Usage

You cannot sunset safely without knowing who uses each version.

// Track version usage
app.use("/v1/*", (req, res, next) => {
  metrics.increment("api.v1.requests", { endpoint: req.path });
  next();
});

---

Interview Questions

---

Further Reading

• RESTful API Design - REST fundamentals and best practices
• GraphQL vs REST - Comparing API styles and their versioning implications
• HTTP/HTTPS Protocol - Understanding the underlying protocol stack
• API Versioning: The Good, the Bad and the Ugly - Industry perspectives on versioning approaches
• RFC 9110: HTTP Semantics - Official HTTP specification including content negotiation
• OpenAPI Specification - Standard for API definitions across versions
• SemVer Official - Semantic versioning specification for SDKs and libraries

---

Quick Recap

Before you ship, run through this checklist:

• Choosing a versioning strategy (URL path, header, or query param) that fits your client base
• Documenting which changes require a new version vs. which are backward compatible
• Setting clear deprecation timelines (minimum 6 months, preferably 12 months)
• Adding Deprecation: true, Sunset: [date], and Link: [successor] headers to all deprecated responses
• Monitoring version usage metrics before sunsetting any version
• Implementing transformation layers for shared database schemas across versions
• Providing migration documentation and checklists for client developers
• Setting max active versions policy (recommended: 2-3 maximum)

---

Conclusion

API versioning is about managing change without breaking clients. URL path versioning is the most common approach because it is explicit and easy to implement. Header versioning keeps URLs clean but is harder to test. Query parameter versioning is simple but less visible.

Good versioning practices include deprecating clearly, giving long transition periods, and monitoring usage. Within a version, avoid breaking changes. Only create a new version when you need to make changes that would break existing clients.

For REST fundamentals, see the RESTful API Design post. For comparing API styles, see the GraphQL vs REST post.