Deprecating an API without breaking clients: Deprecation and Sunset headers, successor-version, and OpenAPI
Most "deprecations" are either silent deletions that break an integration at 2 a.m., or permanent warnings that glow for years until everyone ignores them. A real deprecation is a timeline with a signal clients can automate against, a pointer to the replacement, and a cut-off that actually happens. HTTP and OpenAPI already define the machinery; the missing piece is usually the discipline to use…
A well-executed API deprecation plan provides a timeline, a signal for clients to automate against, a pointer to the replacement, and a cut-off that actually happens. HTTP and OpenAPI already define the necessary machinery, but the missing piece is often the discipline to use all of it together. The four key signals are:
1. Deprecation header (RFC 8594): Every response indicates the endpoint is deprecated as of a specific HTTP-date.
2. Sunset header (RFC 8594): Every response shows when the endpoint will stop working entirely.
3. Link header (rel=successor-version): Every response points to the replacement resource or documentation.
4. deprecated: true extension: Every response marks the operation as deprecated in docs and generated SDKs, with matching dates in the headers.
These signals reach code before developers read the changelog, ensuring clients can automate their migration to the new version. Documenting the headers on the response makes them visible in generated docs and contract tests.
When implementing a deprecation, pick a realistic timeline and stick to it. The window length depends on the stakeholders the API serves. For internal APIs, 4-8 weeks is typical, while public APIs may require 12 months or longer. Announce the deprecation along with the headers and leave the endpoint functional until the sunset date.
Telemetry is crucial for driving migration. Before announcing, track who calls the endpoint, how often, and which user-agents or credentials are used. During the deprecation window, monitor traffic and contact teams whose usage doesn't decline. Send a final reminder near the sunset date to ensure all clients have migrated.
After sunset, decide the endpoint's fate and document it in advance. The clean options are to remove the endpoint and return 404/410 Gone, or redirect to the successor with a 301 status code when the shape remains the same. Avoid returning a silently broken 200 response, as it hides breakage from clients. Deprecated fields and parameters should follow the same discipline as endpoints: marked deprecated in the schema, kept working through the window, described with the replacement, and removed only with a version bump or a documented breaking window.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
