Deprecation

Deprecation is the part of the API lifecycle that everyone wants to skip, and skipping it is exactly what causes the most damage. Every API will eventually be retired — versions get superseded, endpoints become obsolete, products get sunset, companies get acquired, business priorities shift. The question is never whether an API will go away, but how. And the how is almost entirely a business and relationship question, not a technical one. A well-managed deprecation preserves trust, gives consumers time to adapt, and leaves the door open for future business. A botched deprecation breaks integrations, burns developers, and teaches the entire market that your APIs can’t be depended on. I’ve spent years arguing that deprecation deserves as much design attention as any other phase of the lifecycle, precisely because it’s the phase where reputations are made or destroyed.

The first thing to get straight is the expectation problem, because it sits underneath every deprecation conflict. I wrote in 2012 that APIs are forever — wait, no, they can go away at any time — capturing the central tension. Developers building on an API often assume a kind of permanence that the provider never actually promised, and when the API goes away they feel betrayed. I asked directly in 2014: where do developers get the idea that APIs should never go away? The honest answer is that the industry encouraged the assumption. We sold APIs as stable foundations, as infrastructure you could build a business on, and then acted surprised when developers were upset that the foundation moved. Both sides own this. Providers need to be honest from the start that APIs have lifecycles, and developers need to understand that building on someone else’s API is always accepting a dependency that carries risk. I wrote about building your business around Google or any other API back in 2011 precisely to make this risk explicit — the upside of building on a third-party API is real, but so is the exposure.

The building blocks of API deprecation are something I tried to formalize in 2016, because deprecation was being treated as an ad-hoc event rather than a repeatable discipline. The components are knowable: the types of deprecation (a version, an endpoint, a field, an entire product), the runway or notice period you give consumers, the communication channels through which you announce it, the legal and terms-of-service framework that governs your right to deprecate and your obligations when you do, the notification mechanisms that reach consumers where they actually are, and the migration path you provide to whatever replaces the deprecated thing. When you break deprecation down into these building blocks, it stops being a crisis and becomes a process you can plan, document, and execute consistently. The providers who have these building blocks in place handle deprecation gracefully; the ones who improvise handle it badly, every time.

Runway is the single most important variable, and it’s where most deprecations fail. Google’s deprecation policy became the gold standard I pointed to repeatedly — a clear commitment to a defined notice period, typically a year, during which a deprecated API continues to function while consumers migrate. When I wrote in 2015 about good examples of deprecation policies, Google’s was the model precisely because it was a published, predictable, contractual commitment rather than a case-by-case decision. The AdWords API’s release and sunset schedule, which I wrote about in 2017, showed the mature version of this: a rolling, predictable cadence where new versions ship and old versions sunset on a schedule consumers can plan around. Predictability is the gift. A developer can handle the news that an API is going away in twelve months with a clear migration path. What they can’t handle is finding out with two weeks’ notice, or worse, discovering it when their integration silently breaks. The runway is the difference between deprecation as a managed transition and deprecation as an outage.

Communication is the other half of doing it right, and the deprecation page is the artifact I’ve championed most. I wrote in 2018 about having an API deprecation page like Evrythng does — a dedicated, public, persistent page that clearly states what’s being deprecated, when, why, and what consumers should do about it, with clear status labels on affected resources. The deprecation page makes the process transparent and gives consumers a single authoritative reference. On the technical side, the Sunset HTTP header is the machine-readable complement — a way to communicate deprecation timing directly in the API responses themselves, so that automated systems and not just humans can be aware of an impending retirement. By 2020 I was writing about real-time notifications, using GitHub’s proactive system as the example: they don’t just publish a deprecation notice and hope you see it, they detect when your integration is actually using a deprecating feature and notify you specifically. That’s the frontier of good deprecation communication — targeted, proactive, reaching the consumers who are actually affected rather than broadcasting into the void.

My favorite recent example, and the one that captures what good deprecation actually looks like, is the one I wrote about in 2024: celebrating the mundanity of the Department of Labor’s API deprecation notice. It wasn’t dramatic. It wasn’t clever. It was just a clear, professional, well-communicated notice that an API was being deprecated, with the timeline and the path forward stated plainly. And that mundanity is exactly the point — good deprecation is boring. It’s a routine, well-executed process that nobody has to panic about because everything they need to know is right there, communicated clearly and early. When I celebrate a boring government deprecation notice, I’m celebrating an organization that has internalized deprecation as a normal part of operating APIs responsibly, rather than treating it as an embarrassing event to be minimized and hidden.

The opposite — quiet, deceptive, or exploitative deprecation — is where the politics and ethics of the business get ugly. I wrote a deliberately pointed piece in 2016 about extracting as much value from your API developers as you can and then screwing them over in the end, because that extractive pattern is real: build an ecosystem, get developers dependent, harvest the value they create, and then deprecate or restrict access once you’ve gotten what you wanted. Facebook’s quiet deprecation of the Audience Insights API in 2017 — the one that had been used to automate ad targeting during the election — was an example of deprecation used as a quiet political and business maneuver rather than an honest lifecycle decision. The many ways in which APIs are taken away, which I catalogued in 2019, includes a lot of these soft deprecations: not announcing a shutdown outright, but raising prices, throttling rate limits, moving features to enterprise tiers, degrading the free experience, or letting an API rot through neglect. These are deprecations that the provider won’t call deprecations, and they’re often more damaging than an honest sunset because they’re dishonest about what’s happening.

Parse is the case study I keep returning to for how to shut down an entire platform with dignity. When Facebook shut down Parse — a backend-as-a-service that thousands of developers depended on — it could have been catastrophic. Instead, Parse gave a full year of runway, open-sourced the Parse Server so developers could self-host, and provided database migration tools and clear documentation for the transition. I wrote in 2016 that while it absolutely sucked that Parse went away, I wished every service that shut down left behind the same page — the same clarity, the same runway, the same respect for the developers who’d trusted them. This connects to a principle I’d argued for in 2014: please open source your API before shutting it down. When you can’t or won’t keep an API running, the most respectful thing you can do is release the code and the specification so the community can preserve, fork, or continue it. Deprecation doesn’t have to mean destruction. The Pinboard reimplementation of the Delicious API showed how open API designs let communities survive a platform’s death; open-sourcing on the way out is the provider doing that work proactively for their consumers.

The deeper framing I’ve landed on is that deprecation must be designed from the very beginning, not bolted on at the end. I wrote about deprecation as a basic element of the API lifecycle, planned for from inception — you should know, when you launch an API, how you intend to eventually retire it. My lifecycle research from design to deprecation treated retirement as a first-class phase deserving the same rigor as design, deployment, and management. I even built what I called an API purgatory museum and dead pool pages — archives of deprecated APIs — partly as a historical record and partly as a reminder that this is a normal, recurring part of the API story that we should learn from rather than pretend doesn’t happen. The providers who design for deprecation from day one have deprecation policies, deprecation pages, Sunset headers, notification systems, and migration tooling ready before they ever need them. The providers who don’t are the ones improvising a shutdown under pressure, making the decisions that burn their developers and teach the market not to trust them. Deprecation is inevitable. Doing it badly is a choice.

Guidance

API Learnings

APIs

API Governance

API Solutions

API Discovery

API Building Blocks

API Evangelist LLC

Deprecation

References

Guidance Details

Explore more

Discover APIs