evolution
Deprecation Strategy
Retire old APIs and fields safely — with clear signals, telemetry, and a deadline.
Every API accumulates endpoints, fields, and versions that you eventually want to remove — because they are insecure, costly to maintain, or superseded. But you cannot simply delete them: external clients still depend on them, and turning something off without warning breaks integrations and erodes trust. A deprecation strategy is the disciplined process for retiring functionality gracefully, giving consumers time and clear signals to migrate.
A bus route being retired — signs at every stop, a service alert, a "last day" announcement, and finally the route is gone.
Key Concepts
1
A good deprecation has three ingredients: communication, telemetry, and a deadline. You announce the deprecation through documentation, changelogs, and in-band signals — the standard Deprecation header (and the Sunset header naming the planned removal date) on responses from the affected endpoint, so even clients that never read your docs get a machine-readable warning. You instrument the deprecated path to measure who is still using it and how much, turning "we think no one uses this" into hard data, and ideally reach out to the remaining heavy users directly. And you set and honour a firm removal deadline with a generous migration window, so the deprecation actually concludes rather than lingering forever as maintenance burden. Only after usage has dropped to near zero and the deadline has passed do you remove it.
DeprecationSunset
2
The judgement interviewers look for is treating deprecation as a managed lifecycle rather than an event: announce early, signal in the response, measure real usage, support a clear migration path to the replacement, and remove on a committed schedule. The failure modes to avoid are silent removal (breaking clients with no warning) and zombie endpoints (deprecated in name but never actually retired because no one tracked usage or set a deadline), both of which a telemetry-and-sunset approach prevents.
3
What the interviewer is probing.
What the interviewer is probing.
4
1. "What does a good deprecation look like?" *Probing:* the process. *Stalls:* "An email."
*Moves up:* announce with a date, signal in responses with the Deprecation and Sunset headers,
monitor remaining usage, contact the stragglers, then remove.
1. "What does a good deprecation look like?"
5
2. "What is the Sunset header?" *Probing:* the specifics. *Stalls:* "Nothing." *Moves up:* a
standard header giving the date the endpoint stops working, so clients can detect it
programmatically.
2. "What is the Sunset header?"
6
3. "How long should the window be?" *Probing:* the judgement. *Stalls:* "A month." *Moves up:*
proportional to the integration cost and who the consumers are — internal weeks, external partners
often a year.
3. "How long should the window be?"
7
4. "What is the step people skip?" *Probing:* experience. *Stalls:* "None." *Moves up:*
measuring actual usage before removal — turning something off that a quiet but critical consumer
still calls.
4. "What is the step people skip?"