Why API Deprecation Notices Fail Developers

Lucas: So we talk a lot on this show about building APIs that developers love. But there's one moment in an API's life that almost always breeds resentment - and that's when it gets taken away. Luna: You mean deprecation. The day developers wake up to a broken integration and an email they missed. Lucas: Exactly. I think deprecation is the point where the relationship between platform and developer really shows its hand. And most platforms are handling it poorly. Luna: What does 'poorly' look like in practice? Lucas: Let me give you a concrete example. In early 2025, a major identity verification provider sent an email to customers saying that a widely used endpoint would be deprecated - but the sunset date was just four weeks out. Developers who had built deep integrations had to scramble, rewrite, and test under pressure. Luna: Four weeks is brutal. Especially if you're not checking that inbox every day. Lucas: Right. And that's the first problem: relying on email as the sole notification channel. The email might land in spam, or the person who set up the integration left the company. So the first time you hear about it is when your CI pipeline goes red. Luna: So what should a good deprecation notice look like? Lucas: There's actually a standard for this - the IETF's Sunset header, defined in RFC 8594. It's an HTTP header that a server can send on responses to indicate that a resource is likely to be removed or deprecated. It includes a URL where developers can find more information. Luna: I've seen that header in the wild. Stripe uses it, I think. Lucas: They do. And Twilio does too. Those are two of the best examples in the industry. Stripe, for instance, will return a Sunset header months in advance, and they also document the migration path clearly in their API reference. They even provide code examples for the new endpoint side by side with the old one. Luna: But even with the header, if a developer isn't monitoring headers, they still might miss it. Lucas: That's true. So best practice is a multi-channel approach. You send the Sunset header on every response for at least six months. You send periodic emails to the registered owner of the API key. You also publish a deprecation timeline in your changelog, and ideally add a banner in your developer dashboard. Luna: Six months feels like the industry minimum now. I remember when some companies did three months, and developers just accepted it. Lucas: The standard has shifted. GitLab, for example, often gives a full year between deprecation announcement and removal. And they maintain a public deprecation calendar so you can plan upgrades. Luna: But even with all that, there's still the question of what you're actually deprecating. Are we talking about a whole API version, or just a single endpoint? Lucas: Great point. Deprecating an entire version is a different beast. If you're on API v1 and the platform announces v2 and that v1 goes away in a year, that's a big migration. But sometimes it's just one field within a response that's being replaced. And that's where things get subtle. Luna: Yeah, a field deprecation can be easy to miss because the endpoint still works. You just get a new field alongside the old one, and maybe a deprecation notice in the docs. Lucas: And that's where developer experience really matters. A good practice is to include a warning header like 'Warning: 299 - "Field "foo" is deprecated, use "bar" instead"' in the response itself. That way, even if you're not reading the changelog, your logs will show the warning. Luna: You know, this all reminds me of a stat I saw recently. A survey by Postman in 2025 found that 43 percent of developers said they had been burned by an API deprecation that they weren't adequately warned about. Lucas: Forty-three percent. That's huge. And it's a trust issue. Once you've been burned by a platform, you're less willing to build deeply on their next API. Luna: And if you're a platform company, that's existential. You want developers to commit to your ecosystem. Lucas: Yeah, and I think that's the core argument for getting deprecation right. It's not just a technical courtesy - it's a business imperative. If developers don't trust that your API will be stable, they'll build on something else. Luna: And that trust is hard to rebuild. Honestly, if you found today's episode useful for what you're building or running, and you want to support keeping this show ad-free, there's a link where you can do that. If it was worth a coffee to you, that's the link - buy me a coffee dot com slash fexingo. Lucas: Yeah, that kind of support really does help us keep going. So thank you to anyone who does that. Luna: Alright, so back to deprecation strategies. One thing I haven't seen done well is machine-readable deprecation notices. Most companies just write a blog post. Lucas: There's actually a standard for that too. The API Changelog specification, sometimes called 'ChangeLog', allows you to publish a JSON feed of changes, including deprecations, with dates and links. GitHub has something similar with their API changelog. Luna: So you could subscribe to that feed in your CI system and get alerts when something you use is marked for deprecation. Lucas: Exactly. And some tools are starting to integrate that. For example, if you use an API client like Insomnia or Postman, they can check the spec or a feed and warn you that the endpoint you're using has a Sunset header or is in a deprecation list. Luna: That would be a game changer for a lot of teams. I think the gap is that most API providers don't invest in the infrastructure to support that yet. Lucas: Right. And it's a chicken and egg problem. Developers don't demand it because they don't know it's possible, and providers don't build it because they don't see demand. But the companies that do it - like Stripe, Twilio, GitHub - they set a higher bar. Luna: So what's one concrete thing a smaller API provider could do tomorrow to improve their deprecation process? Lucas: Start with the Sunset header. It's trivial to add - just a single line in your web server config or your application code. And set it to at least six months out. Then also make sure your error responses include a deprecation warning if the request uses a deprecated feature. That alone would catch a lot of cases. Luna: And document the migration path clearly. Not just 'use the new endpoint' but show the exact mapping. Lucas: Yes. The best migration guides I've seen include a table with the old request and response, the new request and response, and what changed. Ideally with a code example in multiple languages. Luna: It's a lot of work. But so is dealing with angry developers who have to rewrite their integrations overnight. Lucas: Absolutely. And I think that's the bottom line. Deprecation is an inevitable part of API lifecycle management. But how you handle it determines whether your developers feel respected or betrayed. Luna: Well said. And on that note, I think we've given our listeners plenty to think about the next time they see that Sunset header. Lucas: Yeah. Or the next time they need to deprecate something themselves. We'll be back next week with another angle on building better APIs for developers.