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: Deprecation and Sunset headers, 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.