API Versioning

---
name: api-versioning
description: |
  Trigger when the user asks to version an API, manage breaking changes,
  or plan a migration. Phrases: "API version", "v2", "breaking change",
  "deprecate endpoint", "backward compat".
allowed-tools:
  - Read
  - Write
  - Edit
  - Grep
---

# API Versioning

Pick a versioning strategy and stick to it. Breaking changes are the enemy;
versioning is how you manage them without breaking every client at once.

## Prerequisites

- Existing API with external consumers
- A real breaking change coming (not hypothetical)

## Steps

1. **Pick one strategy.** The three viable options:
   - **URL path** (`/v1/users`, `/v2/users`) - most common, easiest for clients
   - **Header** (`Accept-Version: 2`) - cleaner URLs, harder to debug
   - **Query param** (`?version=2`) - discouraged, caching problems

   For a public API, URL path wins.

2. **Version boundaries are breaking-change boundaries.** Bump versions
   when you:
   - Remove a field from a response
   - Change a field's type
   - Add a required field to a request
   - Change the semantics of a field
   - Change error response format

   Don't bump for additive changes. Adding an optional field or a new
   endpoint stays in the current version.

3. **Support N-1 always, N-2 on a deprecation schedule.** When you ship v2,
   v1 keeps working for at least the deprecation window (3-6 months typical).

4. **Announce deprecations loudly:**
   - `Deprecation` response header pointing at the sunset date
   - `Sunset` header with the exact date
   - Changelog entry
   - Email to known consumers if you have their contacts

5. **Route by version in one place.** The routing layer decides which
   handler serves the request. Handlers shouldn't have `if version >= 2`
   branches.

   ```
   /v1/users -> handlers/v1/users.ts
   /v2/users -> handlers/v2/users.ts
   ```

   Internal code can be shared via service classes below the handler.

6. **Test the deprecation path.** The most common failure is the "it still
   works" illusion - v1 is technically still running, but the underlying
   service class changed incompatibly. Integration tests must run against
   v1 handlers even when v2 is the flagship.

## Guidelines

- Version at the API boundary, never in the database schema.
- Monitor usage per version. Deprecating v1 when 20% of traffic is still v1
  is a breakage event.
- OpenAPI spec per version. v1 and v2 are separate documents.

## Output

- Strategy picked and documented
- New version live alongside old
- Deprecation headers set on the older version
- Dashboard showing per-version traffic