Slide 20 · MIT 02
Formal deprecation process — a schedule with deadlines, not just a label.
“Deprecated” without a shutdown date is “runs forever.” Deprecation is a process, not an announcement.
The deprecation process
A deprecated API version must go through a structured process with defined gates. The goal: zero traffic on the old version by a specific date, after which the endpoint is blocked at the network layer and eventually removed from the codebase.
1️⃣
Announce with a sunset date
Deprecation announcement includes a specific shutdown date (e.g., 6 months out). Publish the date in API docs, send notifications to all registered consumers via email/webhook, add a Deprecation and Sunset HTTP header to every response from the old version so API clients can detect it programmatically. The sunset date is a commitment, not a suggestion.
2️⃣
Monitor traffic to the old version
Track requests to the deprecated version per consumer/IP/API key. Report weekly. As consumers migrate, traffic should decline. Consumers still sending traffic at two weeks before sunset get a direct outreach. If traffic is not trending to zero by sunset, the team must decide: enforce the shutdown (breaking those consumers) or extend the deadline. Both decisions require explicit sign-off.
3️⃣
Block at sunset date — apply patches until then
On the sunset date, block the old version at the API gateway or firewall. Do not wait for traffic to reach zero if the date passes — enforce it. Until the sunset date, the deprecated version must receive the same security patches as the current version. “It’s deprecated, no one should be using it” is not a substitute for applying security patches.
💼 Business takeaway
Ask your team when any deprecated API version is scheduled to actually be shut down. “Deprecated” without a shutdown date means it runs indefinitely and stops receiving security patches — the worst of both worlds.