API Versioning
URL, header and account-pinned versioning, and who carries the burden.
5 to work through
-
intermediate
Your mobile app's API has 14 versions in the field, the oldest three years old. Product wants to remove support. How do you decide?
2 min answer -
advanced
A payments API has thousands of integrators on many SDK versions. How should versioning, deprecation, compatibility testing and migration tooling be designed?
2 min answer -
advanced
A public API must keep every historical version working for thousands of integrators while the team keeps shipping breaking changes. Compare date-pinned per-account versioning with URL versioning and feature flags.
3 min answer -
advanced
An enterprise platform supports many years of API versions simultaneously because customers integrate deeply and upgrade slowly. What does that policy cost, and what would you do differently?
2 min answer -
advanced
You are designing a public payments API. Consumers are numerous, unknown and unmotivated to migrate. How do you handle breaking changes?
2 min answer
5 terms in this topic
Additive-Only Evolution
Establishing the compatibility contract before the first release - unknown fields ignored, unknown enum values defaulted - so that most future change…
practiceAPI Versioning Strategy
The scheme for introducing incompatible change, and the far more important question of how long old versions live and who pays to migrate.
practiceSemantic Versioning
A version scheme where the number itself states the compatibility promise — major for breaking, minor for additive, patch for fixes.
case-studyStripe: Versioning by Account Pinning
Stripe pins each account to the API version it first integrated against and maintains compatibility transformations, so integrations built years ago …
patternVersion Transformation Layer
Implementing an API once against its current shape and expressing every historical version as a pair of request and response transformations, so supp…
Neighbouring topics
API & Integration
General material on integrating systems through contracts.
REST Design
Resources, uniform methods, status codes and statelessness.
GraphQL
Client-specified queries, N+1 resolution and query-cost control.
gRPC APIs
Contract-first RPC, generated clients and protobuf compatibility rules.
Webhooks
Push callbacks, signature verification, ordering and at-least-once delivery.
Backward Compatibility
Which changes are safe, and how to make breakage a build failure.
Contract Testing
Verifying what consumers actually rely on, without a shared environment.
API Documentation
OpenAPI as a machine-checked contract rather than as prose.
Rate Limiting
Algorithms, shared counters, and signalling rejection properly.
Idempotency Keys
Client-generated keys stored atomically with the operation they guard.
Pagination & Filtering
Offset versus cursor, stable ordering and unbounded result sets.
API Error Handling
Error shapes, retryability signals and machine-readable causes.
Event-Driven Integration
Publishing facts rather than commands, and versioning event schemas.
Message Formats
JSON, Protobuf, Avro — schema evolution and payload economics.
Schema Registry
Enforcing compatibility on events the way CI enforces it on code.
Integration Patterns
Routers, translators, splitters, aggregators and dead letter channels.
Legacy Integration
Reaching systems that cannot change, without importing their model.
Partner & B2B Integration
External contracts, onboarding, sandboxes and long deprecation windows.
APIs as Products
Ownership, lifecycle, deprecation policy and developer experience.