Managing API Versions
1. Using URL Path Versioning
| Pattern | Pros | Cons |
|---|---|---|
/v1/users | Visible, cacheable, easy routing | URL changes break clients |
/api/2023-10/users | Date-based, like Stripe | Many versions live |
Example: Path version routing
routes:
- paths: ["/v1/users"] service: users-v1
- paths: ["/v2/users"] service: users-v22. Implementing Header-Based Versioning
| Header | Example |
|---|---|
Accept | application/vnd.api+json;v=2 |
X-API-Version | 2 |
API-Version | 2023-10-15 |
3. Using Query Parameter Versioning
| Pros | Cons |
|---|---|
| Easy to test in browser | Pollutes URL |
| Optional with default | Cache key complexity |
4. Configuring Content Negotiation Versioning
| Aspect | Detail |
|---|---|
| Media type | application/vnd.acme.v2+json |
| Quality value | q=0.9 client preference |
| Fallback | 406 Not Acceptable if no match |
5. Setting Up Version Routing Rules
Example: Combined header + path
routes:
- paths: ["/api"]
headers: { X-API-Version: ["2"] }
service: api-v2
- paths: ["/api"]
service: api-v1 # default when header absent6. Setting Default API Versions
| Strategy | Behavior |
|---|---|
| Latest stable | Newest production version |
| Pinned default | Frozen version (e.g., v1) |
| Client default | API key linked to version |
| Date pinning | Default by creation date |
7. Configuring Backward Compatibility
| Change | Compatible? |
|---|---|
| Add optional field | Yes |
| Add new endpoint | Yes |
| Remove field | No |
| Rename field | No (use alias) |
| Change type | No |
| Tighten validation | No |
8. Implementing Version Deprecation Policies
Deprecation Lifecycle
- Announce: changelog + email (T-180d)
- Add
DeprecationandSunsetheaders - Log usage by client/API key
- Outreach top callers (T-90d)
- Brownouts (5min outages weekly, T-30d)
- Remove version, return 410 Gone
9. Managing Breaking Changes
| Approach | Description |
|---|---|
| Major version bump | v1 → v2 co-exist |
| Feature flags | Per-client opt-in |
| Field versioning | field_v2 alongside |
| Translator middleware | v1 requests → v2 backend |