Designing API Versioning and Evolution
1. Designing API Versioning Strategy
| Strategy | Pros | Cons |
|---|---|---|
| URI path | Cache-friendly, explicit | Pollutes URLs |
| Header (Accept) | Clean URIs | Hard to test in browser |
| Date-based (Stripe) | Pin client to date | Server must maintain transformations |
| Additive only | No version | Requires strict discipline |
2. Designing Backward Compatibility
| Safe Change | Unsafe Change |
|---|---|
| Add optional field | Remove field |
| Add endpoint | Change response shape |
| Loosen validation | Tighten validation |
| Add enum value (with default) | Rename field |
| Add header | Change error semantics |
3. Designing Breaking Change Management
Breaking Change Process
- Announce + deprecation date in changelog
- Add new field/endpoint alongside old
- Mark old as deprecated (header, docs)
- Send Sunset header on old endpoint
- Track usage of old; outreach to clients
- Remove after deprecation window (e.g., 12 months)
4. Designing API Deprecation Strategy
| Mechanism | Detail |
|---|---|
| Deprecation header | Deprecation: true; Sunset: <date> |
| Docs banner | Big visible warning |
| Client warnings | Log on use; email account owners |
| Brownouts | Periodic short outages near sunset |
5. Designing API Sunset Policy
| Window | Use Case |
|---|---|
| 3 months | Internal/private APIs |
| 6–12 months | Partner APIs |
| 12–24 months | Public/critical integrations |
| RFC 8594 | Sunset HTTP header |
6. Designing Schema Evolution
| Format | Rules |
|---|---|
| Protobuf | Don't reuse field numbers; reserved keyword |
| Avro | Default values for new fields; aliases for renames |
| JSON | Optional fields; ignore unknown |
| Compatibility | BACKWARD, FORWARD, FULL (Schema Registry) |
7. Designing Client Migration Strategy
| Practice | Detail |
|---|---|
| Adapter on server | Translate v1 → v2 internally |
| SDK upgrade path | Codemods, migration scripts |
| Dual reporting | Track v1 vs v2 RPS per client |
| Forced upgrades | Last resort: respond 410 Gone |
8. Designing Version Negotiation
| Mechanism | Example |
|---|---|
| Accept header | application/vnd.api.v2+json |
| Custom header | X-API-Version: 2026-05-15 |
| Server default | Latest if not specified |
| Client pinning | SDK locks to known version |
9. Designing Parallel Version Support
| Approach | Trade-off |
|---|---|
| Separate code paths | Clear; duplication |
| Adapter layer | Single core; mapping cost |
| Separate services | Independent deploys; ops cost |
| Feature flags | Per-version behavior toggles |
10. Designing API Changelog Management
| Section | Content |
|---|---|
| Version + date | Header |
| Added | New endpoints/fields |
| Changed | Behavior tweaks |
| Deprecated | With sunset date |
| Removed | Breaking |
| Fixed | Bug fixes |
11. Designing Consumer-Driven Contracts
| Element | Detail |
|---|---|
| Tool | Pact, Spring Cloud Contract |
| Flow | Consumer publishes contract → Producer verifies |
| CI gate | Block prod deploy if contracts fail |
| Broker | Pact Broker tracks per-version compatibility |
12. Designing API Gateway Version Routing
| Strategy | Detail |
|---|---|
| Path prefix | /v1/* → svc-v1, /v2/* → svc-v2 |
| Header | X-API-Version selects upstream |
| Weighted | Gradual cutover from v1 to v2 |
| Per-tenant | Bring users over in waves |