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.