How much notice should we give?

6-12 months for a major version sunset, 3-6 months for a single endpoint, 30 days minimum for security-forced changes. Enterprise contracts sometimes specify longer minimum notice — check your MSAs.

Can we sunset an endpoint if only one customer uses it?

Even one customer needs migration path and notice — usually with direct outreach given the small population. Deprecation isn't about volume; it's about the commitment your API represents.

Should we ever break APIs without deprecation?

Only for security incidents where continued availability creates active harm. Even then, communicate publicly and offer emergency migration support. Everything else waits for the deprecation cycle.

API Deprecation: Policy, Notice Periods, and Sunset

Deprecating an API endpoint is one of the most trust-sensitive things a developer platform.

API Deprecation: How to Retire an Endpoint Without Breaking Your Customers

API deprecation is the process of retiring an endpoint (or a version, or a parameter) that customers actively depend on. Done well, deprecation happens on a predictable timeline with clear migration paths and no surprise breakage. Done poorly, it silently breaks integrations, torches trust, and gives customers a permanent reason to reduce dependency on your platform — the opposite of what a platform strategy needs.

The written deprecation policy

Every mature API has a published deprecation policy covering: (1) versioning scheme (semver, date-based, or major-version), (2) minimum notice period before sunset (typically 6-12 months for major versions, 3-6 months for individual endpoints), (3) commitment to backward-compatible changes within a version, (4) how notice is delivered (email, changelog, response headers), (5) exceptions (security-forced deprecations that can be faster). Publish it and honor it.

The sunset timeline

Standard phases: (1) Announce — publish deprecation notice, update docs with 'Deprecated' badge, start `Sunset` response headers. (2) Warn — 60-90 days before sunset, escalate: email active users, in-console banners, more aggressive headers. (3) Brownout — periodic short outages of the deprecated endpoint 30 days before sunset to force noisy integrations to notice. (4) Sunset — endpoint returns 410 Gone with a link to migration docs.

Identifying who's affected

You can't help customers migrate if you don't know who's still using the deprecated surface. Instrument every call with API key/customer identifier, and surface usage dashboards to CS/AE teams so they can proactively reach out to affected accounts. High-value accounts get white-glove migration support; long-tail accounts get automated communications with clear docs.

Migration paths must exist

A deprecation announcement without a clear replacement is a betrayal. Before announcing deprecation of endpoint X, endpoint Y (or the new pattern) must be shipped, documented, and tested at parity. If the replacement doesn't cover all use cases of the deprecated surface, document the gaps explicitly and extend the timeline until they're closed.

Standards worth adopting

RFC 8594 defines the `Sunset` HTTP header (indicates when a resource will become unavailable). RFC 9745 adds the `Deprecation` header. Both should be set on deprecated endpoints so clients can programmatically detect deprecation. Combined with a documented deprecation policy, they make your API measurably safer to build on.

Frequently asked questions

How much notice should we give?: 6-12 months for a major version sunset, 3-6 months for a single endpoint, 30 days minimum for security-forced changes. Enterprise contracts sometimes specify longer minimum notice — check your MSAs.
Can we sunset an endpoint if only one customer uses it?: Even one customer needs migration path and notice — usually with direct outreach given the small population. Deprecation isn't about volume; it's about the commitment your API represents.
Should we ever break APIs without deprecation?: Only for security incidents where continued availability creates active harm. Even then, communicate publicly and offer emergency migration support. Everything else waits for the deprecation cycle.