# API versioning — convention template

Pick **one** primary signal; mix them only during migrations.

| Style               | Example                                         | Good for                      |
| ------------------- | ----------------------------------------------- | ----------------------------- |
| URL prefix          | `/v2026-05/resources`                           | Public REST, cache-friendly   |
| Header              | `Accept: application/vnd.company.v2+json`       | Avoiding CDN path duplication |
| Stage (API Gateway) | `prod` vs `v2` stages with separate deployments | Canary + rollback by stage    |

**Deprecation:** return `Sunset` + `Deprecation` headers (RFC 8594 pattern) and document cut-off in internal RFC before API Gateway stage deletion.