A platform team ships `/v2/payments` eighteen months ago, sees healthy adoption, and finally deletes the original `/v1/payments` endpoint on a Friday afternoon to clear technical debt before the quarter closes. Within the hour, a mid-sized integration partner's checkout flow starts returning 404s on every transaction, because their integration — built two years earlier by a contractor who has since left — was never migrated, and nobody on either side had checked whether it was still calling `/v1/payments` before the endpoint disappeared. The platform team did nothing wrong by versioning the change; they broke a real, active integration by removing the old version without first confirming it was actually safe to remove.
Deprecation is the discipline that sits between shipping a new version and safely removing the old one — it turns 'we assume everyone has migrated' into a process with three distinct, verifiable steps: announcing that a version's support window has a real end date, measuring whether consumers have actually moved off it, and only then removing it, in a way that still catches whoever the measurement missed. Skipping straight from announcement to removal treats a calendar date as proof of readiness; skipping straight from shipping a new version to removal, with no deprecation period at all, is simply the breaking change versioning was supposed to prevent, arriving on a delay.
Analogy🏏Cricket
🏏 Think of it like cricket: Sachin Tendulkar did not retire from Test cricket by simply not turning up for India's next series. In October 2013, months before his actual final match, he announced that the upcoming two-Test series against West Indies would be his last, naming the exact series and giving the BCCI, the opposition board, broadcasters, and millions of fans real lead time to plan around a fixed, known end date — the historic 200th Test at Wankhede Stadium was scheduled and prepared for specifically because everyone knew, well in advance, that it was the last chance to see him play. Nobody found out he had retired by trying to watch a Test he was supposed to be part of and discovering he wasn't there. Just as Tendulkar's announcement gave every stakeholder a fixed date to plan a farewell around rather than an ambiguous 'sometime soon,' a deprecation notice gives every consumer a fixed date to plan a migration around rather than a version that might disappear on any given deploy. Just as the BCCI didn't cancel the farewell Test itself the moment the announcement was made — the match still had to be played, in full, exactly as scheduled — a deprecated API version keeps working exactly as documented for the entire announced window, right up to the date it was promised to end. The insight is that an ending announced in advance, with a real date attached, is what turns an abrupt loss into something every affected party had the chance to prepare for.
🏏 Showing the Cricket analogy — a Cricket version isn’t available for this concept yet.