Change coupling · Knowledge distribution
Signal the removal before you make it
Breaking changes overwhelmingly ship without any prior deprecation signal — of 251 API versions that introduced a breaking change, 87.3% had deprecated nothing in the previous version — and how the signal is delivered predicts whether clients act on it.
Do this firstMigrate in expand and contract, never in place
Mark it deprecated in a release that still works, say what replaces it, and only then remove it.
The measured practice is worse than the folklore suggests. Almost nine in ten breaking API versions gave no advance signal at all. Of the minority that did deprecate, only 45% supplied a replacement for every affected operation, and three out of 219 used a proactive channel — telling a caller at call time, via headers or an error code, rather than hoping they read the documentation.
That last number is the actionable one. A deprecation nobody encounters is indistinguishable from no deprecation, and the caller is already talking to you.
The decoy
A changelog entry. It is written at the moment of the break, read by people who already upgraded, and reaches nobody still calling the thing you removed.
Evidence
- A First Look at the Deprecation of RESTful APIs: An Empirical Study — IIOf 251 API versions that introduced a breaking change, 87.3% deprecated nothing in the previous version. Among the 219 APIs with any deprecation content, only 45% supplied replacements for every affected operation, and just 3 used a proactive channel — informing callers at call time via headers or error codes rather than relying on documentation.
Last reviewed 2026-08-19.