Versioning & Evolution

Why Version?

APIs evolve. You will need to rename fields, change response formats, or remove endpoints. Without a versioning strategy, every change risks breaking existing clients.

Versioning Strategies

1. URL Path Versioning

The most common and most visible approach:

// Version in the URL path
GET /api/v1/users
GET /api/v2/users

// Express implementation
import v1Router from "./routes/v1";
import v2Router from "./routes/v2";

app.use("/api/v1", v1Router);
app.use("/api/v2", v2Router);

// routes/v1/users.ts
router.get("/users", async (req, res) => {
  const users = await db.users.find();
  // v1 returns flat structure
  res.json(users.map((u) => ({
    id: u.id,
    name: u.name,
    email: u.email,
  })));
});

// routes/v2/users.ts
router.get("/users", async (req, res) => {
  const users = await db.users.find();
  // v2 returns envelope with split name
  res.json({
    data: users.map((u) => ({
      id: u.id,
      firstName: u.firstName,
      lastName: u.lastName,
      email: u.email,
      createdAt: u.createdAt,
    })),
    meta: { total: users.length },
  });
});

Pros: Easy to understand, visible in URLs, easy to route Cons: Duplicates code, hard to maintain many versions

2. Header Versioning

Version is specified in a custom header or the Accept header:

// Custom header
GET /api/users
X-API-Version: 2

// Accept header (content negotiation)
GET /api/users
Accept: application/vnd.myapi.v2+json

// Implementation
app.get("/api/users", async (req, res) => {
  const version = getApiVersion(req);
  const users = await db.users.find();

  if (version === 1) {
    return res.json(formatUsersV1(users));
  }

  res.json(formatUsersV2(users));
});

function getApiVersion(req: express.Request): number {
  // Check custom header first
  const headerVersion = req.headers["x-api-version"];
  if (headerVersion) return Number(headerVersion);

  // Check Accept header
  const accept = req.headers.accept || "";
  const match = accept.match(/application\/vnd\.myapi\.v(\d+)\+json/);
  if (match) return Number(match[1]);

  // Default to latest
  return 2;
}

Pros: Clean URLs, no code duplication Cons: Less visible, harder to test in browser

3. Query Parameter Versioning

// Version in query string
GET /api/users?version=2

// Simple but not recommended for production APIs

Pros: Easy to switch versions for testing Cons: Mixes concerns in query params, caching issues

Backward-Compatible Changes

Not every change needs a new version. These changes are backward-compatible:

// SAFE — Adding new fields (clients ignore unknown fields)
// v1 response
{ "id": 1, "name": "Rahim" }

// Updated response — still compatible with v1 clients
{ "id": 1, "name": "Rahim", "avatar": "https://..." }

// SAFE — Adding new endpoints
GET /api/users/:id/preferences  // New endpoint, does not affect existing ones

// SAFE — Adding optional query parameters
GET /api/users?include=orders  // New filter, existing calls without it still work

// SAFE — Making a required field optional
// Before: name was required
// After: name is optional with a default

// BREAKING — Removing a field
{ "id": 1, "name": "Rahim" }  // "email" was here before, clients depend on it

// BREAKING — Renaming a field
{ "id": 1, "full_name": "Rahim" }  // Was "name", clients break

// BREAKING — Changing a field's type
{ "id": "user_1" }  // Was a number, now a string

// BREAKING — Removing an endpoint
// DELETE /api/legacy-users  — clients still call this

Deprecation Strategy

When you need to retire an old version:

// Step 1: Mark endpoints as deprecated with headers
app.use("/api/v1", (req, res, next) => {
  res.set("Deprecation", "true");
  res.set("Sunset", "Sat, 01 Jun 2026 00:00:00 GMT");
  res.set("Link", '</api/v2>; rel="successor-version"');

  // Log deprecated usage for monitoring
  metrics.increment("api.v1.deprecated_call", {
    endpoint: req.path,
    client: req.headers["user-agent"],
  });

  next();
});

// Step 2: Return warnings in response body
function deprecationWrapper(handler: express.RequestHandler): express.RequestHandler {
  return async (req, res, next) => {
    const originalJson = res.json.bind(res);
    res.json = (body: unknown) => {
      if (typeof body === "object" && body !== null) {
        (body as Record<string, unknown>)._warnings = [
          {
            code: "DEPRECATED_VERSION",
            message: "API v1 is deprecated. Please migrate to v2 by June 2026.",
            docs: "https://docs.myapi.com/migration/v1-to-v2",
          },
        ];
      }
      return originalJson(body);
    };
    handler(req, res, next);
  };
}

// Step 3: After sunset date, return 410 Gone
app.use("/api/v1", (req, res) => {
  res.status(410).json({
    error: {
      code: "VERSION_RETIRED",
      message: "API v1 has been retired. Please use v2.",
      migrationGuide: "https://docs.myapi.com/migration/v1-to-v2",
    },
  });
});

Migration Guide Pattern

Always provide a clear migration guide when introducing a new version:

// Document every breaking change
const migrationGuide = {
  from: "v1",
  to: "v2",
  changes: [
    {
      type: "field_renamed",
      endpoint: "GET /users",
      before: { field: "name", type: "string" },
      after: { fields: ["firstName", "lastName"], type: "string" },
      migration: "Split the 'name' field on space, or use the new fields directly",
    },
    {
      type: "response_wrapped",
      endpoint: "ALL",
      before: "Direct array/object response",
      after: "Wrapped in { data, meta } envelope",
      migration: "Access response.data instead of response directly",
    },
    {
      type: "field_type_changed",
      endpoint: "GET /users",
      before: { field: "id", type: "number" },
      after: { field: "id", type: "string", format: "user_<number>" },
      migration: "Update ID comparisons to use string matching",
    },
  ],
};

Key Takeaways

1. URL path versioning is the standard for public APIs — explicit and cacheable
2. Additive changes are safe — new fields, new endpoints, new optional parameters
3. Removing or renaming fields is breaking — always requires a new version or a migration period
4. Deprecation is a process — announce, warn, sunset, then retire
5. Support at most two versions at a time to keep maintenance manageable
6. Monitor deprecated endpoint usage to know when it is safe to remove old versions