API Deprecation: How to Retire Endpoints Without Burning Integrators
Every API feature eventually reaches the end of its useful life. The endpoint was designed before the domain was understood. The schema made assumptions that no longer hold. A better approach exists. The old version must go. How you handle that retirement determines whether your API’s integrators trust you or resent you.
Deprecation done well is a communication and scheduling problem. Deprecation done poorly is a breaking change that happens without warning.
Deprecation Is a Process, Not an Announcement
The most common mistake in API deprecation is conflating announcing deprecation with doing it. An announcement in a changelog that a developer may not read is not deprecation. Deprecation is a process that ends with the endpoint being unavailable — and the process must give every affected integrator enough time and information to migrate before that happens.
The steps are: announce with a concrete sunset date, emit in-band warnings on every affected request, provide migration documentation, monitor adoption of the replacement, extend the timeline if adoption is insufficient, and sunset on the announced date.
Skipping steps produces integrators who were not ready when the endpoint disappeared. Extending the timeline repeatedly produces integrators who do not take sunset dates seriously. Both outcomes are worse than the alternative: following through on a clear, well-communicated schedule.
Setting the Timeline
The right deprecation timeline depends on your integrator base. For an internal API with a known set of five services, a two-week migration window may be sufficient. For a public API with thousands of integrators ranging from large enterprises with long change cycles to individual developers who maintain their integrations only when they break, eighteen months to two years may still be too short.
The practical minimum for most public APIs is six months. Enterprise customers often have change control processes that require months of internal approval before code can be modified. A six-month timeline is compressible for small integrators but barely sufficient for large ones. Twelve months is more realistic for broadly adopted endpoints.
Announce the timeline when you announce the deprecation. “This endpoint is deprecated” without a sunset date is not actionable. “This endpoint will be removed on December 31, 2027” is. Integrators can plan migrations around a specific date. They cannot plan around “sometime in the future.”
In-Band Deprecation Signals
Changelog announcements reach developers who are actively reading documentation. In-band signals reach developers who are actively making API calls — which is a different, and more reliable, audience.
The HTTP Deprecation header (standardized in RFC 9745) communicates that a response is deprecated and when it will be removed:
Deprecation: true
Sunset: Sat, 31 Dec 2027 23:59:59 GMT
The Sunset header specifies when the resource will no longer be available. Both headers can be included in every response from the deprecated endpoint.
A Link header with rel="successor-version" or rel="deprecation" can point to the replacement or the deprecation documentation:
Link: <https://api.example.com/v2/users>; rel="successor-version"
Logging and monitoring systems that inspect response headers can automatically detect deprecated API usage across an entire fleet of services and generate reports without requiring manual review. This is the operational value of in-band signaling: it enables automated discovery of deprecated usage, which is essential when you have many services you do not fully control.
For your own client libraries and SDKs, emit runtime warnings when deprecated features are called. A warning logged at runtime in the developer’s own application is significantly more noticeable than a response header that requires active inspection.
Migration Documentation
The announcement that an endpoint is deprecated must be accompanied by documentation describing what to use instead. “This endpoint is deprecated, please migrate to the new API” without explaining what the new API is, how it differs, and what migration steps are required is not useful.
Good migration documentation includes: what changed and why, a mapping from deprecated fields and behaviors to their replacements, code examples of the old pattern alongside the new pattern, a description of any behavioral differences that require updated logic (not just a different URL), and an estimated effort level for migration.
For complex migrations — where the new API represents a fundamentally different model, not just a restructured endpoint — consider providing a migration guide that walks through common cases, a compatibility layer that allows incremental migration, and extended timelines for specific large integrators who need more time.
Monitoring Migration Progress
After announcing deprecation, monitor how many callers are still hitting the deprecated endpoint. Most API platforms track this at the API key or account level, enabling targeted outreach to integrators who have not migrated as the sunset date approaches.
Direct outreach — email to accounts still using a deprecated endpoint 90 days before sunset — is significantly more effective than passive documentation. “We noticed your integration is still using the deprecated /v1/users endpoint, which will be removed on December 31. Here is the migration guide.” This combination of specific information and direct communication converts passive awareness into active migration effort.
If usage of the deprecated endpoint is still substantial two months before sunset, treat that as a signal to investigate why and potentially extend the timeline. A sunset that removes an endpoint still used by 20% of active integrators is a breaking change for 20% of your integrators. The point of the process is to ensure migrations are complete before the removal happens.
Soft vs Hard Sunset
A soft sunset makes the deprecated endpoint non-functional for new integrators while continuing to support existing ones. New API keys cannot access the endpoint; existing keys continue to work past the sunset date on a case-by-case basis. This reduces the risk of surprise for long-established integrations while closing the deprecated surface to new usage.
A hard sunset removes the endpoint for everyone on the published date. Hard sunsets create cleaner codebases and eliminate the operational burden of maintaining deprecated infrastructure indefinitely. They also require that migration truly be complete before the deadline — there is no fallback.
For most deprecations, communicate a hard sunset but apply a soft sunset in practice, converting remaining holdouts through direct outreach rather than forced failure. Reserve hard sunsets for endpoints with genuine security or operational risks that make continued availability unacceptable.
What Not to Do
Do not deprecate without a replacement ready. “This is deprecated, we are working on an alternative” leaves integrators in an impossible position. Announce deprecation when the migration path is complete, not when you have decided to remove the old path.
Do not remove deprecated features earlier than announced. The sunset date is a commitment. Breaking it — even by days — destroys the credibility of future sunset announcements. Integrators who built timelines around your announced date and missed it by a week will not trust the next announcement.
Do not let deprecated endpoints linger years past their announced sunset. Extensions signal that sunset dates are negotiable, which reduces their urgency. If the announced date cannot hold, set a new specific date and commit to it. Never announce deprecation without a concrete date.
Deprecation is respect for the integrators who built on your API. Doing it with sufficient notice, clear migration paths, and in-band signals converts a potentially adversarial process into a manageable transition that reflects well on the API’s stewardship.