How much notice should I give before removing an API?

Give consumers enough time to migrate without an emergency — commonly three to six months for public APIs, longer for widely used ones. The deprecation date marks when the endpoint is officially discouraged; the removal date is when it stops working. A generous gap between them earns goodwill.

What is the difference between deprecated and removed?

A deprecated endpoint still works but is officially discouraged and will be removed on a stated date. A removed endpoint no longer exists and returns an error. The window between the two is when consumers must migrate. Announcing deprecation without a removal date often means nobody migrates.

Should I use the Deprecation and Sunset HTTP headers?

Yes, for HTTP APIs. The Deprecation header signals an endpoint is deprecated, and the Sunset header gives the date it will stop working, both machine-readable so client tooling can warn automatically. Pair them with a Link header pointing to this notice for the human-readable details.

What makes a good migration path?

Name the exact replacement endpoint, show how request and response shapes differ, and list the steps in order. The goal is that a developer can follow it without contacting you. Concrete before-and-after examples remove the most friction and the most support tickets.

Where should the deprecation notice be published?

Everywhere consumers will look: the API changelog, the endpoint's reference docs, response headers, and ideally a direct email to known integrators. Redundancy matters — a notice only in the changelog will be missed by teams who do not read it, and a surprise removal damages trust.

API Deprecation Notice Builder

Email me this result

Get this tool's output sent to your inbox, plus one useful tool a week. No spam, unsubscribe any time.

Retire an endpoint without breaking trust

Removing an API endpoint is a breaking change for everyone who depends on it. Done badly, it causes outages and burns trust; done well, it is a non-event because consumers had a clear notice, a real timeline, and an obvious migration path. This builder assembles all three into one notice you can drop into a changelog, the docs, and response headers.

How it works

You provide the exact endpoint being deprecated — method and path — and a short reason. You set two dates: the deprecation date, when the endpoint becomes officially discouraged, and the removal date, when it stops working. The window between them is the migration period your consumers rely on, so make it generous.

The migration section names the replacement endpoint or approach and lists the steps to switch, ideally with before-and-after request shapes. A support contact closes it out. The tool exports the notice as Markdown and also suggests the matching HTTP headers — Deprecation, Sunset, and Link — so client tooling can detect the deprecation automatically, not just humans reading the changelog.

Tips and example

Be concrete. A strong notice reads: deprecated GET /v1/users/list, removed on a stated date, replaced by GET /v2/users which is paginated. Migration steps: switch the base path to /v2, add a page query parameter, and read users from the data array instead of the root. Publish it in the changelog, the reference docs, and as Sunset and Deprecation response headers so integrators are warned in code, not just in an email they might miss.