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.

What is the API Deprecation Notice Builder?

Create a developer-facing API deprecation notice with the deprecated endpoint, sunset and removal dates, the replacement endpoint or approach, a step-by-step migration summary, and a support contact. Export clean Markdown for changelogs and docs. It runs free in your browser on Gera Tools, with nothing uploaded.

API Deprecation Notice Builder

Name: API Deprecation Notice Builder
Creator: Gera Tools
License: https://creativecommons.org/licenses/by/4.0/

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.

The Deprecation and Sunset HTTP headers

RFC 8594 (Sunset) and RFC 9745 (Deprecation) define machine-readable response headers that signal deprecation status to API consumers. Adding these to every response from a deprecated endpoint lets client SDKs, API gateways, and monitoring tools detect and alert on deprecated calls automatically — without requiring developers to read the changelog:

Deprecation: Sat, 01 Jan 2025 00:00:00 GMT
Sunset: Sun, 01 Jun 2025 00:00:00 GMT
Link: <https://docs.example.com/deprecation/v1-users-list>; rel="deprecation"

The Deprecation header marks when the endpoint became deprecated. The Sunset header marks when it will stop responding. The Link header with rel="deprecation" points to the human-readable notice (such as the Markdown output from this builder). Together they give both automated systems and developers everything they need to respond.

How much notice is enough?

The right migration window depends on your consumer base:

Consumer type	Recommended notice window
Internal only (your own team)	2–4 weeks
External partners with SLAs	3–6 months
Public API with unknown consumers	6–12 months
Widely adopted (thousands of integrations)	12+ months

Announcing deprecation without a firm removal date is one of the most common failures. Consumers will not migrate until there is a deadline because migration has a cost and teams prioritise other work. A credible removal date is what makes the notice actionable.

Writing a migration path that actually works

A migration path fails if consumers must contact you to understand it. A migration path that works:

Names the exact replacement — not “use the new v2 API” but GET /v2/users?page=1&limit=100
Shows what changed — a before-and-after table of request parameters, response fields, and error codes
Explains the reason — why the old endpoint is going away (pagination, security, performance) gives context that makes developers more willing to migrate
Tells them what to test — one or two curl examples with real-looking payloads they can try immediately
Provides a rollback period — if you can keep the old endpoint alive in a read-only or limited mode for a brief window after the sunset date, say so

Practical example

A strong notice for removing a list endpoint: deprecated GET /v1/users (returns unpaginated results that exceed memory limits at scale), removed on a stated date, replaced by GET /v2/users with required page and limit parameters. Migration steps: update the base path to /v2, add ?page=1&limit=100 to the request, change your loop to iterate through pages until an empty data array is returned instead of a single response. Publish 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 and not in time.