Your public API has 2,000 integrators. You need a breaking change. How do you handle versioning and migration?
Short answer
Avoid breaking changes where possible through additive evolution; if unavoidable, introduce a new major version in parallel, publish migration guides and timelines, use deprecation and sunset headers, track usage per integrator, provide tooling and support, and retire the old version only when usage is near zero or the deadline passes with notice.
Detailed answer
- Design for compatibility: additive fields, tolerant readers, new endpoints instead of changed semantics.
- New major version (
/v2) side by side; shared backend with translation adapters where possible. - Communication: changelog, migration guide, SDK updates, emails, developer portal banners.
- Signals:
DeprecationandSunsetheaders, usage analytics per API key, direct outreach to top integrators. - Timeline: e.g. 12 months for public APIs; contractual commitments respected.
- Retirement: brownouts (temporary planned failures) before final shutdown to surface remaining consumers.
What the interviewer expects
Empathy for consumers, data-driven deprecation and a concrete process.
Common mistakes to avoid
Silent changes, no usage tracking, too short notice.