Implementing API Versioning
1. Using URI Versioning
| Aspect | Detail |
|---|---|
| Format | /v1/orders |
| Pros | Visible, cache-friendly, easy routing |
| Cons | URLs change with versions |
| Common | Most public APIs (Stripe, GitHub) |
2. Using Header Versioning
| Header | Example |
|---|---|
| Accept | Accept: application/vnd.shop.v2+json |
| Custom | X-API-Version: 2 |
| Pros | Stable URLs |
| Cons | Harder to test in browser; CDN cache key |
3. Using Query Parameter Versioning
| Aspect | Detail |
|---|---|
| Format | /orders?api-version=2 |
| Pros | Easy to test |
| Cons | Mixes filters and version semantics |
| Use | Date-based versions (e.g. ?v=2026-05-01) |
4. Using Content Negotiation
| Element | Detail |
|---|---|
| Vendor media type | application/vnd.shop.v2+json |
| Profile parameter | application/json; profile="https://api.shop.com/order/v2" |
| Server picks | Best match from Accept |
5. Implementing Backward Compatibility
| Rule | Detail |
|---|---|
| Add only | New optional fields/endpoints |
| Don't rename | Keep old field; add new one |
| Don't tighten | Validation can only relax |
| Default values | For new required fields |
| Tolerant reader | Ignore unknown fields |
6. Managing Breaking Changes
| Change | Strategy |
|---|---|
| Field removal | New version; deprecate first |
| Type change | New field name; old stays |
| Behavior change | Feature flag or new endpoint |
| Required ↑ | Major version bump |
7. Deprecating Old Versions
| Step | Detail |
|---|---|
| Announce | Changelog + email + in-product |
| Sunset header | Sunset: Wed, 31 Dec 2026 23:59:59 GMT |
| Deprecation header | Deprecation: true + Link: rel="successor-version" |
| Brownouts | Periodic 410 to surface usage |
| Sunset window | 6–12+ months for public APIs |
8. Supporting Multiple Versions
| Approach | Detail |
|---|---|
| Single codebase + adapters | Convert v1 ↔ v2 at edges |
| Separate deployments | v1 frozen, v2 active |
| Gateway translation | Backwards compat at LB |
| Cost | Limit to ≤ 2 active versions |
9. Implementing Version Routing
| Layer | Mechanism |
|---|---|
| Gateway | Path/header routes to version pool |
| Service mesh | VirtualService matches |
| Subdomain | v2.api.shop.com |
10. Documenting Version Changes
| Doc | Detail |
|---|---|
| CHANGELOG.md | Per-version diff |
| Migration guide | v1 → v2 mapping |
| OpenAPI per version | Hosted side-by-side |
| Deprecation notes | In docs + headers |
11. Using Semantic Versioning
| Component | Bump When |
|---|---|
| MAJOR | Breaking change |
| MINOR | Backward-compatible feature |
| PATCH | Backward-compatible fix |
| Public APIs | Expose only MAJOR in URL/header |
12. Implementing API Lifecycle Management
| Stage | Detail |
|---|---|
| Design | OpenAPI-first, review |
| Beta | Limited audience, breaking allowed |
| GA | Stable contract, semver |
| Deprecated | Sunset announced |
| Retired | 410 Gone |
| Tools | Backstage, Apigee, Kong, Tyk |