Managing API Versioning Patterns
1. API Versioning Pattern
| Strategy | Detail |
|---|---|
| URL Path | /v1/orders |
| Header | X-API-Version: 2 |
| Query Param | ?version=2 |
| Content Negotiation | Accept: application/vnd.shop.v2+json |
| Hostname | v2.api.shop.com |
2. URL Path Versioning Pattern
| Pros | Cons |
|---|---|
| Most discoverable | URI changes break REST hypermedia |
| Cache-friendly per version | Couples version to resource identifier |
| Easy testing in browser | — |
3. Header Versioning Pattern
| Aspect | Detail |
|---|---|
| Header | Custom (X-API-Version) or standard (Accept-Version) |
| Pros | URI stable; per-resource versioning |
| Cons | Less discoverable; harder to test |
4. Query Parameter Versioning Pattern
| Aspect | Detail |
|---|---|
| Format | ?api-version=2024-05-01 |
| Pros | Easy to test, opt-in |
| Cons | Cache fragmentation; clutter |
| Used By | Azure REST APIs (date-based) |
5. Content Negotiation Versioning Pattern
| Aspect | Detail |
|---|---|
| Mechanism | Accept: application/vnd.shop.v2+json |
| Pros | RESTful; URI stable |
| Cons | Complex client config; tooling friction |
6. Semantic Versioning Pattern
| Component | Bump When |
|---|---|
| MAJOR (X.0.0) | Breaking change |
| MINOR (0.X.0) | Backward-compatible feature |
| PATCH (0.0.X) | Backward-compatible bugfix |
| For APIs | Usually only MAJOR exposed in URL |
7. Backward Compatibility Pattern
| Rule | Allowed? |
|---|---|
| Add optional field | Yes |
| Add new endpoint | Yes |
| Rename field | No (use Expand & Contract) |
| Remove field | No (mark deprecated, remove in next major) |
| Tighten validation | No (rejects previously valid input) |
| Change type | No |
| Add new required field | No (must be optional) |
8. Forward Compatibility Pattern
| Practice | Detail |
|---|---|
| Tolerant Reader | Ignore unknown fields |
| Use Defaults | For missing optional fields |
| Schema-First | Generate clients from schema (Protobuf, OpenAPI) |
| Benefit | Old clients survive new server features |
9. Deprecation Pattern
| Step | Action |
|---|---|
| Announce | Docs + email + dashboard |
| Header Signal | Deprecation, Sunset (RFC 8594) |
| Track Usage | Per-client metrics; identify stragglers |
| Migration Guide | Code examples; new vs old |
| Sunset Date | Min 6-12 months for public APIs |
| Remove | Confirm zero traffic; remove code |
Example: Deprecation Headers
HTTP/1.1 200 OK
Deprecation: Tue, 01 Jul 2026 00:00:00 GMT
Sunset: Tue, 31 Dec 2026 00:00:00 GMT
Link: <https://api.shop.com/v2/orders>; rel="successor-version"10. Parallel Versions Pattern
| Aspect | Detail |
|---|---|
| Run Side-by-Side | v1 and v2 served simultaneously |
| Implementation | Same service different routes, or separate services |
| Cost | Maintain N versions; bug fixes ported to all supported |
| Limit | Cap supported versions (e.g., last 2 majors) |