How to Write an API Deprecation Notice

A deprecation notice needs four things in the first paragraph: what is being removed, the exact date it stops working, the replacement, and what happens to callers who do nothing. Everything else is supporting material, and burying any of those four is how a planned deprecation becomes an incident on someone else’s system.

Deprecation is a promise being withdrawn. Handling it well is largely about respecting that.

The Four Facts, Immediately

Before:

As part of our ongoing efforts to improve the developer experience and modernize our platform, we are excited to announce a number of enhancements to our API. Over the coming months we will be introducing a range of improvements that will make integration simpler and more powerful. As part of this evolution, some legacy endpoints will be sunset in due course.

After:

GET /v1/customers is deprecated and will stop responding on 15 March 2027.

Replace it with GET /v2/customers, which returns the same fields plus pagination. Migration guide below; most callers need to change the URL and read data instead of the top-level array.

After 15 March 2027, requests to /v1/customers return HTTP 410 Gone. They will not fall back to v2.

The second version can be triaged in fifteen seconds by an engineer who has 40 other things to do. That is the standard, because that is who is reading.

Never use “sunset” or “evolve” as a euphemism for removal. Engineers reading quickly need the word “removed” and a date.

Give Enough Time

The timeline should reflect how much work migration actually is and who depends on you.

Six months is a reasonable minimum for a public API. Twelve is standard for anything widely used, and enterprise contracts often specify longer. For an internal API with three known callers, six weeks and a conversation may be plenty.

Announce once, then remind. A common schedule: announcement at the start, reminders at 90 days, 30 days, and 7 days, and a notice on the day. People who read the first email will have forgotten by month five.

Make the Migration Concrete

The single biggest determinant of whether people migrate on time is how much thinking they have to do.

Show before and after request and response examples side by side. Name every field that changed, was renamed, or disappeared. Call out behavior differences that are not visible in the shape of the response: different default page size, different sort order, different error codes, stricter validation.

Those invisible differences cause the migrations that “worked” in testing and broke in production.

If you can provide a compatibility shim, a mapping table, or a script, do. Every hour you spend on migration tooling saves the collective hours of everyone who calls you.

Tell People If They Are Affected

If you have usage data, use it. A generic announcement to everyone is much weaker than a targeted message saying “your integration called this endpoint 4,200 times last week.”

Where possible, expose it in the product too: a warning in the dashboard, a Deprecation and Sunset header on responses, a log line. Multiple channels matter because your announcement will be read by one person at the customer, and that person may have left.

Do Not Move the Date Casually

Extending a deprecation deadline under pressure teaches every consumer that your dates are negotiable, and the next deprecation will be ignored until the extension arrives.

If you must extend, say why, give a new firm date, and say that it is final. Once.

Conversely, do not shorten a date after announcing it, and do not remove something early because usage looks low. Low usage is often one important customer.

The Tone

Deprecation notices are read by people who are being given work they did not ask for. A cheerful, excited tone about improvements lands badly.

Neutral, factual, and slightly apologetic about the disruption is right. Acknowledge the cost in one sentence: “We know this means work on your side, and here is what we have done to reduce it.”

A Wrivio Context for this could say:

Rewrite this as an API deprecation notice for developers. Neutral technical register, no marketing language, no words like excited, journey, or enhanced. State what is removed, the exact removal date, the replacement, and the behavior after removal in the first paragraph. Use the word removed rather than sunset. Keep every endpoint path, date, field name, HTTP status code, and version number exactly as written, and do not add migration steps or guarantees that are not in the original.

Press Ctrl+Shift+Space, paste the draft your product team wrote, and check the diff line by line. Endpoint paths, dates, and status codes are the entire payload of this message, and a rewrite that changes 410 to 404, or shifts a date by a month, will produce real broken integrations.

After the Date

Do not remove it silently. Return 410 Gone with a body explaining what happened and where to go, rather than a 404 that looks like a bug.

Keep the migration documentation online for at least a year afterwards. Someone will hit an old integration in eight months and search for the endpoint name.

Common Questions

How do I reach people who ignore email?

Response headers, dashboard warnings, and log messages reach the engineer rather than the account owner. Use all three.

Should I break it briefly as a test?

Scheduled brownouts, short deliberate outages before the final date, are an established practice and effective at surfacing callers who have not migrated. Announce them clearly in advance.

What if a large customer cannot migrate in time?

Handle it as a contract conversation, not by moving the public date. A private extension is much cheaper than eroding every future deadline.

Download Wrivio for Windows to strip marketing language out of technical notices before they reach developers.