API Versioning Without Regret

Quickstart

If you want API versioning without regret, start here. These steps are the highest leverage because they prevent breaking changes long before you argue about whether to version in URLs, headers, or media types.

Overview

APIs are long-lived interfaces between independent release cycles. Your server can deploy ten times a day; your clients might update once a month, or never (hello, enterprise). That gap is why API versioning exists: it lets you evolve the server while keeping older clients functional.

You’ll notice a theme: versioning is a last resort. You use it when you truly must change the contract in a way that will break existing clients. The rest of the time, you evolve through additive changes, sensible defaults, and stable semantics.

Core concepts

1) The contract is bigger than JSON fields

Your API contract includes anything a client can reasonably depend on: endpoint paths, HTTP methods, status codes, required fields, validation rules, pagination semantics, sort order guarantees, error formats, and even rate limits. When you change any of these in an incompatible way, you’ve made a breaking change (even if the JSON “looks similar”).

2) Compatibility is about client behavior

A change is “breaking” if it causes a correct client to behave incorrectly: crash, mis-handle errors, silently corrupt data, or perform the wrong action. This is why “we never removed the field, we just changed what it means” is one of the most dangerous moves you can make.

3) Where to put the version: pick the one you can operationalize

People argue about “the best” versioning style. In reality, the best style is the one your tooling, docs, and gateways can enforce consistently. Your choice should optimize for: discoverability, cache correctness, testability, and migration ergonomics.

4) Deprecation & sunset: the “adult” part of versioning

Versioning without a removal plan creates a museum: dozens of old versions you can’t shut off because nobody knows who’s still using them. A healthy API has a lifecycle: introduce → measure adoption → deprecate → sunset → remove.

5) Consumer-driven contracts: how to avoid surprise breakage

The server team rarely knows every way clients use the API. That’s why compatibility checks work best when they’re driven by clients: contract tests, schema validation, and “what do real clients send/expect?” telemetry.

Step-by-step

This is a pragmatic workflow you can reuse for every API change. It keeps the focus on compatibility first, version numbers second. You can run it with REST, GraphQL, or RPC-style APIs (the principles are the same: preserve contracts and migrate intentionally).

Step 1 — Classify the change: additive, breaking, or semantic?

Step 2 — Design for compatibility (prefer widening over mutating)

When you want to change a response, the safest move is to add a new field and leave the old one intact until clients migrate. When you want to change behavior, create a new endpoint, a new resource, or a new representation rather than changing semantics in place.

Step 3 — Choose your versioning mechanism (once)

Pick a mechanism that matches your ecosystem and commit to it. Below is a concrete example of media type versioning and path versioning side-by-side. Even if you don’t use these exact headers, the idea matters: make the version selection deterministic and visible.

# Option A: Path versioning (explicit URLs)
curl -sS https://api.example.com/v1/users?limit=10

# Option B: Media type versioning (content negotiation)
curl -sS https://api.example.com/users?limit=10 \
  -H "Accept: application/vnd.example.users.v2+json"

# Option C: Header versioning (often easiest behind a gateway)
curl -sS https://api.example.com/users?limit=10 \
  -H "X-API-Version: 2"

Step 4 — Implement parallel versions (don’t fork the whole world)

Supporting two versions doesn’t mean duplicating your entire backend. A clean implementation shares domain logic and splits only the contract layer: request parsing, response shaping, and validation. Think “two adapters, one core.”

import express from "express";

const app = express();

// Minimal version negotiation: default to v1, allow explicit v2
function getRequestedVersion(req) {
  const hdr = String(req.header("X-API-Version") || "").trim();
  if (hdr === "2") return 2;
  return 1;
}

function addDeprecationSignals(res, { deprecated, sunsetISO }) {
  if (!deprecated) return;
  // These are widely recognized conventions; use what fits your org.
  res.setHeader("Deprecation", "true");
  res.setHeader("Sunset", sunsetISO); // e.g., "2026-07-01T00:00:00Z"
  res.setHeader("Link", '<https://docs.example.com/migrate/v2>; rel="deprecation"');
}

app.get("/users", (req, res) => {
  const v = getRequestedVersion(req);

  if (v === 1) {
    addDeprecationSignals(res, { deprecated: true, sunsetISO: "2026-07-01T00:00:00Z" });
    // v1 shape (legacy)
    return res.json({ users: [{ id: "u_1", name: "Ada" }] });
  }

  // v2 shape (new contract)
  return res.json({
    data: [{ id: "u_1", displayName: "Ada" }],
    meta: { count: 1 }
  });
});

app.listen(3000, () => console.log("API listening on :3000"));

Step 5 — Version documentation and schemas

Your docs are part of the contract. If you ship v2 but keep a single doc page that “kinda” describes both, you’ll get inconsistent integrations and support load. Prefer separate, explicit docs per version (or a clearly switchable doc view).

openapi: 3.0.3
info:
  title: Example API
  version: "2.0"
paths:
  /v1/users:
    get:
      deprecated: true
      summary: List users (v1 - deprecated)
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        name: { type: string }
  /v2/users:
    get:
      summary: List users (v2)
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id: { type: string }
                        displayName: { type: string }
                  meta:
                    type: object
                    properties:
                      count: { type: integer }

Step 6 — Deprecate, measure, and sunset

Deprecation that works looks boring: a clear date, clear messaging, and a dashboard that shows adoption moving in the right direction. If you can’t measure who is still on v1, you can’t safely remove it.

Common mistakes

Most API breakages are predictable. Here are the patterns that create the most pain, plus the practical fix you can apply immediately.

FAQ

Do I always need API versioning?

No. Most API evolution can be done without a new version by making additive changes (new optional fields, new endpoints, new capabilities). You need API versioning when you must change the contract in a way that would break existing clients (types, required fields, semantics, error behavior).

Is URL versioning (/v1) bad practice?

No. It’s often the most practical option for public REST APIs because it’s explicit, easy to document, and easy to test. The “bad practice” is not the location of the version—it’s shipping breaking changes without a migration plan, or accumulating versions with no sunset policy.

What counts as a breaking change in a JSON API?

Removing/renaming fields or endpoints, changing a field type, making an optional field required, changing validation rules in a way that rejects formerly valid requests, changing status codes/error formats, and semantic changes (same field name, different meaning) are all breaking. Adding optional fields is usually safe.

How long should I support an old API version?

Support windows depend on your client ecosystem. Public APIs and enterprise customers often need longer windows. A common approach is a fixed window (e.g., 6–18 months) plus a measurable threshold (e.g., “remove when <1% traffic for 30 days”). What matters most: it’s explicit, communicated, and backed by telemetry.

How do I version GraphQL or gRPC?

GraphQL typically versions through deprecation at the field level and additive schema changes, not “v1/v2 endpoints.” gRPC with protobuf is designed for compatibility if you follow protobuf evolution rules (don’t reuse field numbers, don’t change types, prefer adding new fields). The principle is the same: avoid breaking changes; use deprecation and parallel fields when needed.

How do I prevent accidental breaking changes?

Make compatibility a gate. Use API review checklists, contract tests, and schema validation in CI. Track version usage and test representative clients (or generated SDKs) against staging before you ship changes to production.

Cheatsheet

A scan-fast checklist you can keep next to your PR template.

Wrap-up

“API versioning without regret” is mostly about not needing versions too often. If you treat your API as a contract, prefer additive evolution, and run deprecation as a measured rollout, you can change your system without waking up to broken clients.

Want to go deeper? The related posts below connect the dots: consistent API design rules, clean architecture boundaries, and resilience patterns that make migrations safer.

Related posts

• API Design Rules: Consistency Beats Cleverness
• Clean Architecture Explained With a Tiny Example App
• Domain-Driven Design Lite: The Useful 20%
• Monolith vs Microservices: A Decision Guide for 2026
• Event-Driven Architecture: When Events Actually Help
• Resilience Patterns: Timeouts, Retries, Circuit Breakers