api-versioning-strategy

# API Versioning Strategy

Produce a complete API versioning strategy document that gives a service team durable, consistent rules for evolving their API without breaking consumers. This document covers the versioning scheme selection (with rationale), lifecycle policy from introduction through sunset, a precise breaking-change classification, and all the communication artifacts a team needs when deprecating a version. Engineers should be able to hand this document to a new team member or external consumer and have them understand exactly what to expect.

## Required Inputs

Ask for these if not already provided:
- **API type** — REST, GraphQL, or gRPC (each has different versioning mechanics)
- **Current versioning approach** — URL path (`/v1/`), request header, query parameter, or none; if none, document starts fresh
- **Number of existing versions and active consumer count** — needed to size the lifecycle policy and migration scope
- **Deprecation timeline constraints** — any hard deadlines (contract SLAs, compliance windows, annual release cycles)
- **Consumer type** — internal teams only, external partners, public API, or mix (affects communication channel choices)

If any input is missing, ask before producing the document. For GraphQL, note that the versioning approach differs substantially (schema evolution over versioning) and tailor the scheme section accordingly.

## Output Format

---

# API Versioning Strategy: [Service Name]

**Owner:** [Team Name]
**API Type:** [REST / GraphQL / gRPC]
**Document Version:** 1.0
**Last Reviewed:** [Date]
**Next Review:** [Date + 6 months]

---

## 1. Versioning Scheme

### Selected Approach: [URL Path / Request Header / Query Parameter]

| Scheme | Example | Pros | Cons | Verdict |
|--------|---------|------|------|---------|
| URL Path | `/v2/orders` | Visible in logs and bookmarks; trivial to route | Violates strict REST resource identity; clutters URL space | **Recommended for public-facing REST APIs** |
| `Accept` Header | `Accept: application/vnd.[service].v2+json` | Keeps URLs clean; proper content negotiation | Harder to test in browser; less visible in logs | Recommended for internal APIs with controlled clients |
| Query Parameter | `/orders?version=2` | Easy to retrofit without URL restructuring | Often missed in client code; cache-key complications | Acceptable only for read-heavy APIs already in production |
| GraphQL Schema Evolution | Field deprecation + `@deprecated` directive | No versioning needed for additive changes | Requires disciplined schema design | **Recommended for GraphQL APIs** |

**Rationale for [chosen scheme]:** [One paragraph explaining why this scheme fits the API type, consumer type, and operational context provided. Reference the specific inputs — e.g., "Because this API has external partners who integrate via generated clients, URL path versioning provides the most predictable routing behavior and eliminates header negotiation complexity."]

### Version Format

```
[Base URL]/v{MAJOR}/{resource}

Examples:
  https://api.[company].com/v1/orders
  https://api.[company].com/v2/orders/{id}/items

Version identifier: integer only (v1, v2, v3)
No minor versions in the URL — minor/patch changes are non-breaking and deployed continuously.
```

---

## 2. Version Lifecycle Policy

### Lifecycle Stages

```
  STABLE ──────────────────────────────────────────────────►
      │
      ├─ STABLE        Active development, full SLA, new consumers allowed
      │
      ├─ DEPRECATED    Announced, timeline posted, migration docs live.
      │                New consumers blocked. Existing consumers receive warnings.
      │
      ├─ SUNSET        Requests return HTTP 410 Gone + migration pointer.
      │                30-day window before routing is removed.
      │
      └─ RETIRED       Routing removed, docs archived, no traffic accepted.
```

| Stage | Duration | SLA Applies | New Consumers Allowed | Required Action |
|-------|----------|-------------|----------------------|-----------------|
| Stable | Until superseded | Yes — full | Yes | None |
| Deprecated | [12 months / adjust per constraint] | Yes — degraded acceptable | No | Migrate before sunset date |
| Sunset | 30-day window | Best-effort only | No | Migrate immediately |
| Retired | Permanent | None | No | — |

**Minimum Stable Period:** A version must remain Stable for at least [6 / 12] months before deprecation can be announced.

**Maximum Simultaneous Versions:** No more than [2] versions in Stable or Deprecated status at any time. Releasing v3 requires committing to a sunset date for v1 in the same announcement.

---

## 3. Breaking vs. Non-Breaking Change Classification

Apply this table before every API change. If a change is marked Breaking, it requires a new major version. When uncertain, default to Breaking.

| Change Type | Specific Example | Classification | Rationale |
|-------------|-----------------|----------------|-----------|
| Remove a response field | Delete `order.legacy_id` from response | **Breaking** | Clients reading this field will null-pointer or fail |
| Rename a field | `user_name` → `username` | **Breaking** | Clients referencing old name receive null |
| Change field type | `"amount": "10.00"` → `"amount": 10.00` | **Breaking** | Type mismatch at deserialization |
| Make optional field required | `email` required in POST body | **Breaking** | Existing callers omitting it receive 400 |
| Remove an endpoint | `DELETE /v1/widgets/{id}` removed | **Breaking** | Existing callers receive 404 |
| Change HTTP method | `GET /search` → `POST /search` | **Breaking** | Bookmarked or cached GET calls fail |
| Change authentication scheme | API key → OAuth2 | **Breaking** | All clients must re-authenticate |
| Restructure error response shape | Error JSON schema changed | **Breaking** | Error-handling code misparses responses |
| Expand enum values (response) | New `status: "on_hold"` value returned | **Breaking** | Switch statements with no