Skip to content
← ALL NOTES

Four years at Apple, and what it taught me about deprecation

How to retire an API politely — and why “sunset” is now a verb I use at parties.

I spent four years on Apple Media Products, and a surprising amount of that time was spent taking things away. Two legacy embed APIs, a handful of undocumented query parameters people had built businesses on, and one endpoint so old that the person who wrote it had left before I finished university.

Shipping features teaches you how to be interesting. Retiring them teaches you how to be trustworthy, which is harder and lasts longer.

Announce it twice as early as feels necessary

Every partner integration has exactly one person who understands it, and that person is on parental leave. A twelve-month notice is not generosity, it is arithmetic: two quarters for them to notice, one to plan, one to actually do it, and one because something else caught fire in between.

A deprecation is a promise about the future, so it has to be dated, written down, and boring.

Instrument before you argue

The first thing I did with the older embed API was log every call with the partner ID attached. Two weeks of data replaced a month of speculation: 94% of traffic came from four partners, and 6% came from a long tail of installations nobody had a contact address for. That number changed the plan. We wrote personally to four people and gave the tail a full extra year.

Make the new path obviously better

Nobody migrates for hygiene. They migrate because the replacement is faster, smaller, or removes a workaround they hate. If the new API is merely tidier from the inside, you have not built a migration — you have built a chore and attached a deadline to it.

  1. Publish the sunset date in the response headers, not just the changelog. Machines read headers; humans read changelogs eventually.
  2. Ship a one-page migration guide with a working before-and-after, and make it the first search result.
  3. Turn the old path off for one hour, twice, in the two months before the date. A scheduled brownout finds the integrations your logs missed.

We got both APIs off the books without breaking a partner integration. Mostly. One radio station in Ohio had hardcoded a redirect through a server we had never heard of, and they found out during the second brownout — which is precisely what brownouts are for.

— O.P., FORT GREENE, STILL APOLOGISING TO OHIO