Chapter 8 — API Versioning & Documentation

The why

The moment you ship an API, you've made a promise. Versioning is how you keep that promise while still moving forward.

Core concepts

The three versioning strategies

Every API versioning strategy boils down to where you put the version identifier. Each has tradeoffs that affect caching, routing, and client complexity.

1. URL Path Versioning (/v1/, /v2/)

// GET /api/v2/users/42
// GET /api/v1/users/42 (old version, still supported)

The most common approach. GitHub, Stripe, and most public APIs use this.

Advantages:

• Dead simple for clients — change the URL.
• Works with every HTTP client (curl, browsers, SDKs).
• Easy to route at the infrastructure level (nginx, load balancer): location /api/v1/ → old service, location /api/v2/ → new service.

Disadvantages:

• "v2" implies a new resource, but semantically it's the same resource with different representation — violates REST purism.
• Requires service infrastructure changes for each new version (new routes, new deployments).
• Can lead to URL sprawl if not carefully managed.

// Express example: URL versioning with route prefixing
import { Router } from 'express';
 
const v1Router = Router();
v1Router.get('/users/:id', v1UserController.show);
 
const v2Router = Router()

2. Header Versioning (Custom Header or Accept Header)

// GET /api/users/42
// Header: Accept: application/vnd.myapp.v2+json
// or: API-Version: 2024-03-15

Used by Azure DevOps, Twilio, and increasingly popular for internal/microservice APIs.

Accept header variant (content negotiation):

app.get('/api/users/:id', (req, res) => {
  const acceptHeader = req.headers.accept || '';
  if (acceptHeader.includes('vnd.myapp.v2')) {
    return

Advantages: URL stays clean — same resource identifier regardless of version. Better aligns with REST's content negotiation principle. Easy to default to latest version without client changes.

Disadvantages: Harder to test in browser (can't type a URL into the address bar). Caching proxies may not consider the custom header as part of the cache key. Debugging is harder — the URL alone doesn't tell you which version is being served.

3. Query Parameter Versioning (?version=2)

The simplest to implement but the least recommended for public APIs.

Breaking vs non-breaking changes

The entire point of versioning is to manage breaking changes. But what counts as "breaking"?

Breaking changes (require a new version):

• Removing an endpoint or HTTP method
• Removing a response field
• Changing a field's type (string → number, string → object)
• Changing authentication requirements
• Adding a required request parameter
• Changing error response structure

Non-breaking changes (safe within a version):

• Adding a new endpoint
• Adding an optional request parameter
• Adding a new response field (clients ignore unknown fields — Postel's Law)
• Relaxing validation (accepting more input formats)
• Adding new enum values to an existing field
• Changing rate limits (increasing, not decreasing)

Deprecation: How to sunset a version

You can't support /v1 forever. Sun-setting requires communication and time:

// Server: Add deprecation headers to v1 responses
app.use('/api/v1', (req, res, next) => {
  res.set('Deprecation', 'true');
  res.set('Sunset

The Sunset header (RFC 8594) tells clients exactly when the endpoint will stop working. The Deprecation header signals that the resource is deprecated. The Link header with rel="deprecation" points to documentation about the migration.

Deprecation timeline:

1. Day 0: Release v2, announce deprecation of v1. v1 continues to work normally.
2. Month 3: v1 responses include deprecation headers. Dashboard shows v1 vs v2 traffic.
3. Month 6: Email remaining v1 users directly. Offer migration support.
4. Month 9: v1 returns 410 Gone for 5% of requests (brownout) on Tuesdays to wake up inattentive clients.
5. Month 12: v1 fully removed. All requests return 410 Gone with a clear migration message.

Brownout technique: Temporarily returning errors for a deprecated version forces clients that ignored your deprecation notices to finally pay attention. GitHub and Stripe both use this pattern.

OpenAPI: Documentation as code

OpenAPI (formerly Swagger) is the industry standard for describing REST APIs. Write a spec, and documentation, client SDKs, and server validation all derive from it.

# openapi.yaml
openapi: 3.1.0
info:
  title: My API
  version: 2.0.0
  description: |
    ## Deprecation Notice
    Version 1 is deprecated and will be sunset on 2025-03-01.
    See [migration guide](/docs/migration-v1-v2).
 
servers:
  - url: https://api.example.com/v2
    description: Production (v2)
  - url: https://api.example.com/v1
    description: Production (v1, deprecated)

Generating OpenAPI from code (not the other way around):

The best workflow: your code is the source of truth. Annotations in your code generate the OpenAPI spec. The spec generates documentation.

// Express + swagger-jsdoc approach:
/**
 * @openapi
 * /users/{id}:
 *   get:
 *     summary: Get a user by ID
 *     parameters:
 *       - in: path
 *         name: id
 *         required: true
 *         schema:
 *           type: string
 *           format: uuid
 *     responses:
 *       200:
 *         description: User found

Linting your OpenAPI spec with Spectral:

Spectral is Stoplight's open-source API linter. It catches spec errors and enforces style guides:

# .spectral.yaml
extends: [[spectral:oas, all]]
rules:
  path-params-exist: error
  operation-operationId: error
  my-org-versioning:
    description: All paths must include a version prefix
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: ^/api/v\d+/

Run in CI:

npx @stoplight/spectral-cli lint openapi.yaml

If the lint fails, the build fails. This prevents undocumented or malformed API changes from reaching production.

Real-world example: How GitHub versions their API

GitHub's REST API is one of the largest public APIs, serving billions of requests per day. Their versioning approach is nuanced:

Primary strategy: Accept header with media type. GitHub uses custom media types like application/vnd.github.v3+json. The v3 indicates API version 3 (their current REST API). This is content negotiation — the URL stays the same, the response format changes based on the Accept header.

Secondary strategy: Date-based feature previews. For new features that aren't stable yet, GitHub uses the Accept header with a feature preview name: application/vnd.github.nebula-preview+json. This lets early adopters opt into beta features. When the feature stabilizes, the preview is removed and the feature becomes part of the base version.

Sunset policy: GitHub commits to supporting each API version for at least 24 months after announcing a replacement. They use the Sunset header and send emails to repository owners. Their deprecation window is generous because enterprise customers have slow upgrade cycles.

Documentation: GitHub's API docs are generated from an OpenAPI spec that lives in their open-source rest-api-description repository. The spec is the source of truth; the docs site is a build artifact. This means community contributions (fixing a description typo) go directly to the spec and flow into docs automatically.

The lesson: GitHub treats their API as a product. Versioning, deprecation windows, feature previews, and documentation are all part of that product's user experience.

Common mistakes

Production notes

• Route both versions through the same load balancer. This lets you monitor v1 vs v2 traffic side-by-side in your metrics dashboard. Set up alerts when v1 traffic drops below a threshold (indicating migration is complete).
• Use feature flags for gradual rollouts within a version. Instead of deploying a breaking change as v2 immediately, use a feature flag in v1 that increments a counter. When all v1 clients have been migrated, promote the flag to the default.
• Version your internal services too. Microservices calling each other need versioning as much as public APIs. Use date-based header versioning (API-Version: 2024-03-15). It's easier to reason about "the March 2024 version" than "v17."
• Monitor Sunset deadlines. Create calendar reminders for sunset dates. An expired sunset deadline that you forgot about means you're supporting an extra version indefinitely — technical debt that accumulates silently.
• Include API version in your logging and monitoring. Every log line, every trace span, every error report should include the API version. When debugging a production issue, knowing it only affects v1 clients narrows your investigation significantly.

Performance notes

• Documentation sites should be statically generated. Don't serve API docs from your production API server. Build docs from OpenAPI at deploy time and serve from a CDN or separate docs subdomain.
• Don't version at the database level. Each API version should read from the same database with the same schema (ideally). Versioning transforms (field renaming, type conversion) should happen in the API layer, not in stored procedures or views.
• Cache API responses by version. CDN and reverse proxy cache keys must include the version identifier. For URL versioning, the URL naturally handles this. For header versioning, configure Vary: Accept or Vary: API-Version on your cache.
• Avoid runtime version resolution in hot paths. Don't look up version handlers dynamically on every request. Register routes at startup time. The version dispatch should be O(1) — ideally handled by the HTTP framework's routing table.

Security notes

• Don't leak version information unnecessarily. While version headers are necessary, don't include detailed version info in error stack traces or debug endpoints. An attacker enumerating your versions gains information about your deployment cadence and potentially unpatched older versions.
• Rate limit by version. v1 (deprecated) might get lower rate limits to encourage migration. v2 gets full capacity. This is a soft incentive for clients to upgrade.
• Validate OpenAPI specs for PII exposure. Generated docs might accidentally expose internal field names, database column names, or test data. Review generated OpenAPI specs before publishing.
• Authentication changes across versions require special handling. If v2 adds OAuth while v1 uses API keys, your auth middleware must handle both without exposing tokens across version boundaries.
• Scan for zombie endpoints. Run automated scans that call every endpoint in your OpenAPI spec and verify it either responds correctly or returns the documented deprecation response. Endpoints that silently break are security liabilities.

Exercises

Beginner

1. Add versioning to an existing Express API: Take a simple CRUD API (users, posts) and add URL path versioning. Create /api/v1/users and /api/v2/users with a breaking change (e.g., rename name to fullName in the response). Run both versions simultaneously.

2. Write an OpenAPI spec: Write an OpenAPI 3.1 YAML spec for a 3-endpoint user API. Include path parameters, query parameters, request bodies, and response schemas. Validate with Spectral.

Intermediate

3. Implement accept-header versioning: Modify the Express API to use Accept header versioning (application/vnd.myapp.v2+json). Add content negotiation logic that defaults to v1 when no version header is present. Write tests that verify both versions respond correctly.

4. Automate OpenAPI generation: Set up swagger-jsdoc (or a similar tool for your framework) to generate an OpenAPI spec from JSDoc comments in your code. Add a build script that generates the spec and fails if the spec is invalid. Add Spectral linting to the pipeline.

Advanced

5. Build a deprecation system: Implement a complete deprecation pipeline: (a) Add Deprecation and Sunset headers to deprecated endpoints. (b) Log v1 vs v2 usage to a metrics system. (c) Build a dashboard showing migration progress. (d) Implement brownout logic that returns 410 for 10% of deprecated endpoint requests.

6. Backward-compatible schema evolution: Design a response schema that supports adding fields without breaking v1 clients, removing fields without breaking v2 clients, and changing field types through a transitional period. Implement the server-side transformation logic. Write integration tests that verify both v1 and v2 clients receive correct responses.

Interview questions

Beginner

1. Q: What are the three common places to put an API version identifier? A: (1) URL path (/api/v1/users), (2) HTTP header (Accept: application/vnd.myapp.v2+json or API-Version: 2), (3) Query parameter (/api/users?version=2). URL path versioning is most common for public APIs; header versioning is preferred for internal microservices.

2. Q: What's the difference between a breaking and non-breaking change? A: A breaking change requires clients to modify their code to continue working (removing a field, changing a type, removing an endpoint). A non-breaking change is backward-compatible (adding a new endpoint, adding an optional field, adding a new enum value). Non-breaking changes don't require a new API version.

3. Q: What is OpenAPI? A: OpenAPI (formerly Swagger) is a specification for describing REST APIs in a machine-readable format (YAML or JSON). It defines endpoints, parameters, request/response schemas, authentication methods, and server URLs. OpenAPI specs can generate documentation, client SDKs, and server validation code.

Senior

4. Q: You discover a security vulnerability in your v1 API. v1 has 5,000 active clients but is scheduled for sunset in 6 months. Do you patch v1 or force-migrate everyone to v2? A: Patch v1 immediately for security — a known vulnerability is unacceptable regardless of deprecation status. Then accelerate the v1→v2 migration: reduce the sunset window to 2 months, send direct emails to v1 users, implement brownouts (5% of v1 requests return 410) after 1 month to force attention. Security patches transcend versioning strategy.

5. Q: How do you handle database schema changes across API versions when both versions read from the same database? A: Never let API versioning drive database schema changes directly. The database schema should be designed to support all active API versions. Techniques: (1) Add columns, never remove or rename them until all versions using the old name are sunset. (2) Use database views for version-specific field mapping. (3) Handle field renaming at the API layer with a transformation layer per version.

6. Q: Your team wants to move from REST to GraphQL. How do you version this transition for existing REST API consumers? A: GraphQL typically doesn't version its schema (it uses deprecation of individual fields instead). The transition: (1) Deploy the GraphQL endpoint alongside REST. (2) Build the GraphQL schema as a superset of REST functionality. (3) Announce REST v1 is feature-frozen. All new features go to GraphQL. (4) After 6-12 months, announce REST sunset. (5) Provide a migration guide mapping REST endpoints to GraphQL queries. (6) Consider an automatic translation layer (REST→GraphQL proxy) for clients that can't migrate quickly.

Summary

API versioning is not about picking the cleverest URL scheme — it's about keeping promises to your developers. URL path versioning (/v1/, /v2/) wins for public APIs because it's universally understood. Header-based versioning shines for internal microservices where URL cleanliness matters. Whatever you pick, the non-negotiable parts are: (1) a clear definition of breaking vs non-breaking changes, (2) a documented deprecation timeline with Sunset headers, (3) OpenAPI specs generated from code and linted in CI, and (4) monitoring that tells you who's still on old versions. Documentation isn't a separate concern — it's the other half of versioning. An API without docs is a puzzle; a versioned API without docs is a puzzle with extra steps.

Quick recall

• URL path versioning (/v1/) — simplest, most common, works everywhere.
• Header versioning (Accept or API-Version) — cleaner URLs, harder to test.
• Query param versioning (?version=2) — easiest to implement, least recommended.
• Breaking change = clients must update code. Non-breaking = backward-compatible.
• The Sunset header (RFC 8594) tells clients when an endpoint stops working.
• Brownouts (temporary 410 errors) force inattentive clients to notice deprecation.
• OpenAPI + Spectral linting in CI = documentation that can't drift from code.
• Never version at the database layer. Handle transformations in API code.
• Deprecation timeline: announce → warn headers → brownout → sunset. Minimum 6 months.

Quiz

1. Which HTTP header (RFC 8594) tells clients the date after which an endpoint will no longer work? A: Sunset

2. Adding an optional response field is a breaking or non-breaking change? A: Non-breaking (clients ignore unknown fields)

3. What tool from Stoplight lints OpenAPI specs? A: Spectral

4. GitHub uses which versioning strategy for their REST API? A: Accept header with custom media types (application/vnd.github.v3+json)

5. What temporary error technique forces clients to notice deprecation? A: Brownouts (returning 410 Gone for a percentage of requests)

6. True or false: API docs should be served from the same server as the API. A: False — they should be statically generated and served from a CDN or docs subdomain.

7. What's the minimum recommended deprecation period before sunsetting a public API version? A: 6 months (12 months for enterprise APIs like GitHub)