Since 2016 we have retired thirty-one API endpoints. I went back through all of them last month, reading the emails, the changelog entries and the angry replies, and tried to work out why some deprecations passed without a single support ticket while others consumed a quarter.
The surprise was how little the technical details mattered. The easy ones weren't the small ones, or the old ones, or the ones with few users. They were the ones where we had been honest early.
An API is a promise with a long tail
When a developer builds against your API, they are making a bet that you will still be there, unchanged, when their code is running in production three years from now — probably after the person who wrote it has left. The integration is cheap to build and expensive to touch. That asymmetry is the entire source of your leverage, and it is why abusing it is so corrosive.
What the good ones had in common
- A long, boring timeline. Twelve months, announced once, in writing, with a specific date.
- A named replacement that was already available and documented before the announcement.
- Migration help that cost the customer nothing: a codemod, a compatibility shim, or a person to talk to.
- Reminders that escalated gently — at 9, 6, 3 and 1 months, never as a surprise.
Deprecation isn't a deadline you impose. It's a schedule you negotiate, mostly in advance and mostly in silence.
What the painful ones had in common
The three worst deprecations in our history all shared a trait: we announced them as decisions when they should have been proposals. In each case we had good internal reasons. In each case we told customers what we'd decided, not what we were considering, and in each case we learned about an essential use case from the first angry email.
The cost nobody counts
Every deprecation has two bills. The first is the engineering cost of migrating, which both sides can estimate. The second is the loss of confidence, which neither can. A customer who has been burned once starts to wrap your API in an abstraction layer, adds fallbacks to another provider, or simply stops recommending you. None of it shows up in a dashboard.
What we do now
- Treat the announcement as the start of a conversation, with a public discussion thread.
- Publish usage numbers so customers can see they aren't alone.
- Never remove anything on a Friday, a holiday, or the last week of a quarter.
- Keep a public list of every endpoint we've ever retired, and why.
The most useful thing we ever did was the last one. Publishing our history makes us behave better, and it lets customers calibrate how much to trust us. That, in the end, is what an API is: a standing request to be trusted.



