API Versioning Graveyard
Teams version their APIs to maintain backward compatibility — v1, v2, v3. Each version promises to keep existing integrations working while new features ship on the latest version. The intent is good: don't break your consumers. But API versions rarely get deprecated. Consumers don't migrate because migration has cost and no user-facing benefit. The API team now maintains 3-5 versions simultaneously. Bug fixes must be backported. Security patches must be applied to all versions. New features must work across version boundaries. The engineering cost of maintaining the graveyard of old API versions grows linearly while the team size stays flat. Eventually, the oldest versions become unmaintainable — the engineers who built them have left, the code is undocumented, and the consumers who depend on them are the ones least likely to migrate.
What people believe
“API versioning maintains backward compatibility and keeps consumers happy.”
| Metric | Before | After | Delta |
|---|---|---|---|
| API versions maintained | 1 | 3-5 simultaneously | +400% |
| Engineering time on version maintenance | 0% | 20-30% of API team | +25% |
| Consumer migration rate | Expected 80%/yr | Actual 10-20%/yr | -75% |
| Feature velocity | Baseline | -30% due to version constraints | -30% |
Don't If
- •You're creating a new API version for every breaking change instead of batching them
- •You have no deprecation timeline or enforcement mechanism
If You Must
- 1.Set hard deprecation dates with contractual enforcement
- 2.Provide automated migration tools for consumers
- 3.Use additive-only changes to avoid versioning when possible
- 4.Charge premium support rates for deprecated API versions
Alternatives
- Additive API evolution — Add new fields/endpoints without breaking existing ones — no versions needed
- GraphQL — Clients request exactly what they need — schema evolution without versioning
- Consumer-driven contracts — Test against actual consumer usage, not assumed compatibility
This analysis is wrong if:
- API consumers consistently migrate to new versions within the announced deprecation timeline
- Maintaining multiple API versions costs less than 10% of API team engineering time
- API versioning doesn't constrain feature development velocity compared to unversioned APIs
- 1.Stripe API Versioning Strategy
Stripe maintains 100+ API versions through automated compatibility layers
- 2.Google API Design Guide: Versioning
Google's approach to API versioning and the challenges of deprecation at scale
- 3.Thoughtworks: API Versioning Anti-Patterns
Common mistakes in API versioning that lead to maintenance burden
- 4.Postman State of APIs Report
Survey data showing API version deprecation timelines are rarely met
This is a mirror — it shows what's already true.
Want to surface the hidden consequences of your engineering decisions?