Versioning APIs
1. Using URI Versioning
| Pattern | Example |
|---|---|
| Path prefix | /v1/users, /v2/users |
| Subdomain | v1.api.example.com |
| Pros | Visible, cacheable, easy to test |
| Cons | Violates "URI = resource" purist view |
2. Using Header Versioning
| Header | Example |
|---|---|
| Custom header | X-API-Version: 2 |
| Date-based (Stripe) | Stripe-Version: 2026-01-15 |
| Pros | Clean URIs |
| Cons | Less visible, harder to test in browser |
3. Using Query Parameter Versioning
| Pattern | Example |
|---|---|
| Query param | /users?api-version=2 |
| Pros | Easy to test, optional |
| Cons | Can be forgotten; cache key issues |
4. Using Content Negotiation Versioning
Example: Vendor Media Type Versioning
GET /users/42
Accept: application/vnd.example.v2+json
HTTP/1.1 200 OK
Content-Type: application/vnd.example.v2+json5. Implementing Backward Compatibility
| Safe Change | Breaking Change |
|---|---|
| Add optional field | Remove/rename field |
| Add optional query param | Make optional → required |
| Add new endpoint | Change response shape |
| Loosen validation | Tighten validation |
| Add enum value (with caveat) | Remove enum value |
6. Handling Deprecated Versions
| Header | Use |
|---|---|
Deprecation: true | Mark endpoint deprecated (RFC 9745) |
Sunset: <date> | End-of-life date (RFC 8594) |
Link: <...>; rel="successor-version" | Point to replacement |
Warning: 299 - "Deprecated; use v2" | Human-readable |
7. Communicating Version Changes
| Channel | Content |
|---|---|
| Changelog | Per-version diffs, migration notes |
| Email to API consumers | Pre-deprecation, mid, sunset |
| Developer dashboard | Banner with usage of deprecated APIs |
| Status page / blog | Public announcements |
8. Managing Multiple Versions Simultaneously
| Strategy | Trade-off |
|---|---|
| Separate codebases | Isolation; duplication |
| Adapter layer | Single core, version-specific transforms |
| Feature flags | Per-version behavior in same code |
| Limit to N versions | e.g. current + 1 prior |
9. Using Semantic Versioning
| Component | When to Bump |
|---|---|
| MAJOR | Breaking change |
| MINOR | Backward-compatible new features |
| PATCH | Backward-compatible bug fixes |
| API URL versioning | Usually only MAJOR (/v1, /v2) |
10. Documenting Version Differences
| Doc Element | Content |
|---|---|
| Per-version OpenAPI spec | Maintain separate specs |
| Migration guide | Step-by-step v1→v2 changes |
| Diff tool | Auto-generated diff page |
| Code samples | Per-version SDK examples |