API Design interview question · Most asked
How should you version an API?
Summary
Common approaches are URL path versioning (/v1/orders), header/media-type versioning (Accept: application/vnd.acme.v2+json) and date-based versions (Stripe's Stripe-Version: 2024-06-20). Whatever you choose, avoid breaking changes within a version, add fields compatibly, and deprecate with notice.
Longer Answer
Additive changes (new optional fields, new endpoints) don't need a new version; renames, removals, type changes and semantic changes do. Publish deprecation timelines with Deprecation/Sunset headers, monitor usage of old versions, and provide migration guides.
Key Points
- Path, header or date versions
- Additive changes are safe
- Breaking changes need versions
- Deprecation + Sunset headers
More most-asked API Design questions
- What makes an API RESTful, and what are good REST design practices?
- Which HTTP methods are safe and idempotent, and why does it matter?
- Which HTTP status codes should an API use, and when?
- Compare offset pagination and cursor (keyset) pagination.
- How do idempotency keys work for POST requests?
- When would you choose GraphQL over REST, or gRPC over both?