HardExperience level: 8-15 years1 min read

How do you evolve a public API without breaking existing clients?

Reviewed by Gurusankar M.

Asked inAmazonMicrosoftGoogleStripe-like
#backward compatibility#deprecation#contract#breaking change#api design
Report issue

Short Answer

Change additively: add optional fields/endpoints, never remove or repurpose existing ones, keep defaults stable, and tolerate unknown fields. For unavoidable breaks, introduce a new version, support both during a published deprecation window, and communicate via docs + Deprecation/Sunset headers.

On this page

Concept Made Simple

Coffee Chat Question

“How do you evolve a public API without breaking existing clients?”

Remember It Faster

Mind Map Answer

Safe
add optional fields/endpoints
Breaking
remove/rename/retype/make-required
Process
new version + deprecation window
Signal
Deprecation/Sunset headers + docs

Think Beyond the Expected

What If?

You must remove a field thousands of clients still use — what's the rollout?

Don't remove it abruptly. Mark it deprecated in docs and via Deprecation/Sunset headers, monitor who still uses it (telemetry), reach out to those consumers, keep it working through the announced window, then remove only after usage drops — ideally behind a new version.

Real World

Stripe/GitHub-style API longevity comes from additive evolution + clear deprecation policies; the costliest API mistakes are silent breaking changes that take down integrations.

Interviewer's Expectation

Keywords they're listening for:

  • additive changes
  • what counts as breaking
  • tolerant reader
  • deprecation window + headers
  • usage telemetry

Common Mistakes

  • Removing/renaming fields in place
  • Repurposing an existing field's meaning
  • No deprecation communication

Best Practices

  • Evolve additively; tolerate unknown fields
  • Publish + signal deprecations (Sunset header)
  • Use contract tests + usage telemetry

Follow-up Questions

  1. What is the 'tolerant reader' principle?
  2. How do consumer-driven contract tests help?
  3. How do you measure who still uses a deprecated field?

Continue Learning with AI

Take this question deeper with your favourite AI assistant. Pick a depth, copy the prompt, or open it directly — AI is your learning companion, not a shortcut.

Plain-language foundations

I'm preparing for a software engineering interview and want to understand this from scratch, as a beginner.

Topic: Versioning (REST APIs)
Interview question: "How do you evolve a public API without breaking existing clients?"

Please:
1. Explain the core idea in simple, plain language, using an everyday analogy.
2. Define any technical terms you use.
3. Walk through one small, concrete example.
4. Finish with a single sentence I can easily remember.

Keep the tone friendly and assume I'm new to this topic.
Open inChatGPTGeminiClaude

Was this answer helpful?

Affiliate links

Tools for Your Developer Workspace

Equipment for a comfortable, productive setup.

As an Amazon Associate I earn from qualifying purchases.