Skip to content
Back to blog
Insights

What a decade of API deprecations taught us about trust

We have retired 31 endpoints since 2016. The ones that went well had little in common technically — and almost everything in common socially.

Daniel Okoye

Engineering Manager, Platform

Published
Reading time
2 min
Electricity pylons and power lines stretching toward a setting sun on a flat horizon
Photograph via Unsplash

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

  1. A long, boring timeline. Twelve months, announced once, in writing, with a specific date.
  2. A named replacement that was already available and documented before the announcement.
  3. Migration help that cost the customer nothing: a codemod, a compatibility shim, or a person to talk to.
  4. 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.

Written by

Daniel Okoye

Engineering Manager, Platform

Daniel manages the platform group — APIs, databases and the deploy pipeline. He runs most of Leaf's incident reviews.

Keep reading

All stories