You cannot deprecate an API by asking nicely.
Every migration guide in the world will not move a caller who does not have a date. The date is the technology.
The hook
A platform team I work with announced the deprecation of their internal v1 API eight months ago. Beautiful migration guide. Sat on Confluence. Had a "when do I need to migrate?" section that said "by end of Q3." Last week I checked. Twelve services still calling v1. Every bug fixed twice. Every security patch written twice. On a whiteboard somewhere, a graph of migration progress shaped like a flat line. I have been on both sides of this. It never works the polite way. Never.
नाहीं काम माझें काज तुह्मां सवें · I Have No Work With You Now
नाहीं काम माझें काज तुह्मां सवें । होतें गुप्त ठावें केलें आतां ॥ १ ॥
व्यभिचार माझा पडिला ठाउका । न सर ती लोकांमाजी जालें ॥ २ ॥
न धरावा लोभ कांहीं मजविशीं । जालें देवपिशी तुका ह्मणे ॥ ३ ॥
A private commitment costs energy every day, because it must be defended in a hundred small conversations. A public commitment ends those conversations.
What I keep seeing
The platform team is having the same conversation with each of the twelve caller teams. In each conversation, the caller is polite, sympathetic, and says they will get to it after their current sprint. The platform team is maintaining two API surfaces. Twelve identical conversations, each ending with "next sprint," each meaning "never."
I have been the caller in this situation too. I am not proud of it. The migration was always three days of work. I just had other three-day tasks that had deadlines attached to them, and the deprecation did not. That is the whole problem, stated plainly.
The mechanics
An API deprecation is not a technical migration. It is a coordination problem across N teams, each optimising for their own sprint. The technical migration inside any one caller is usually small: a few days of work. The coordination is what costs.
There are exactly two mechanisms that force a coordination problem to a conclusion. One: a hard cutoff date, publicly announced, enforced in the code. On that date, v1 returns HTTP 410 Gone. Not a warning. Not a 200 with a deprecation header. Not a Slack ping. 410. Two: the platform team migrates every caller themselves, which is expensive but tractable.
Everything in between is fiction. Deprecation headers nobody reads. Sunset dates everyone ignores because the previous three were extended. Metrics dashboards showing caller counts, viewed only by the platform team. If your deprecation strategy is "we told them," you do not have a strategy. You have a wish.
Where Tuka comes in
The abhanga describes the state of a deprecated-but-not-removed API with startling precision. "होतें गुप्त ठावें केलें आतां": what was hidden is now known. Deprecation gets its power the moment the removal date is public and unmovable. Until then, the deprecation is private negotiation. The platform team hopes each caller will migrate. Each caller hopes the date will slip. Every stakeholder is running a small private bet against the others. The expected value is zero. The maintenance cost is real.
Tuka's next move: "न धरावा लोभ कांहीं मजविशीं" (do not hold this hope about me). The kindest thing a platform team can say to a caller is: we will not extend the date. Plan accordingly. Extensions given "just this once" teach every caller that all future dates are negotiable too. One extension poisons every deprecation you will ever attempt.
What I would actually do
Do not announce a deprecation until you have committed to enforcing the removal date in code. Pick the date. Put the 410 behind a feature flag scheduled to flip on that date. Announce it clearly: on this date, at this time, v1 returns 410, whether you have migrated or not. Two months before, publish a leaderboard of remaining v1 callers, ordered by call volume, updated daily. The leaderboard is not mean-spirited. It is a coordination technology. You will feel like a bad neighbour for a week. Your platform team will get their sprint capacity back for a year.
Chetan Dhandal