What is the difference between the Deprecation and Sunset HTTP headers?

The Deprecation header indicates when an API endpoint was deprecated (the date it was marked for removal). The Sunset header (RFC 8594) indicates when the endpoint will actually stop working. Both are dates. Use them together: Deprecation tells clients how long the endpoint has been deprecated, and Sunset tells them how much time they have left to migrate. The Sunset header is more widely recognized and supported by API management tools.

Should I use 301 redirect or 410 Gone for removed endpoints?

Use 301 Moved Permanently or 308 Permanent Redirect only when the new endpoint accepts the same request format and returns a compatible response, so existing client code works without changes. Use 410 Gone when the endpoint is removed and no direct equivalent exists, or when the request and response formats changed significantly between versions. A 410 clearly communicates that the resource was intentionally removed and includes a link to the migration guide. Never use 404 for intentionally removed endpoints because it does not distinguish between never existed and was removed.

How long should the deprecation period last before removing an endpoint?

Industry standard is 6 to 12 months between deprecation announcement and removal. For public APIs with paying customers, err toward 12 months. For internal APIs, 3 to 6 months may be sufficient. Factors to consider: how many consumers use the endpoint, how complex the migration is, contractual obligations, and your historical precedent. Whatever timeline you choose, communicate it clearly via the Sunset header and respect it by not removing early.

How do I track which clients are still using deprecated endpoints?

Log every request to deprecated endpoints with the client identifier (API key ID, OAuth client ID, or IP address), user agent, and timestamp. Aggregate this data into a dashboard showing daily request count per endpoint, unique clients per day, and usage trends. Use your API management platform or a custom middleware that sends metrics to your monitoring system. Before the sunset date, generate a report of active clients and reach out via email or in-app notifications.

Should I include deprecation notices in the response body or just headers?

Use both. Headers are the standard mechanism and are supported by API management tools, SDK generators, and monitoring platforms. However, many developers never inspect response headers during development. Including a _deprecation object in the response body makes the deprecation visible in API responses, debug logs, and test output. Keep the body notice optional or in a separate field so it does not break clients that parse the response with strict schemas.

Handling Deprecated Endpoints Gracefully