API Deprecation: Definition, Best Practices, Examples

What is API deprecation?

API deprecation is the formal process of phasing out an endpoint, version, parameter or response field. The deprecated piece keeps working for an announced period while consumers are told what to use instead. At the end of that period it is removed, which is called the sunset, and anyone still calling it breaks.

It is the contract between an API provider and its consumers: this is changing, here is the date, here is the replacement.

The deprecation lifecycle

Signalling it in HTTP

Two standard response headers make deprecation machine-readable. Deprecation (RFC 9745, March 2025) says the resource is or will be deprecated, as a date written as @ followed by Unix seconds. Sunset (RFC 8594) says when it is expected to stop responding, as an HTTP date that should not be earlier than the deprecation date. A Link header with rel="deprecation" can point to the documentation.

HTTP/1.1 200 OK
Deprecation: @1780272000
Sunset: Tue, 01 Dec 2026 00:00:00 GMT
Link: <https://api.example.com/docs/v1-sunset>; rel="deprecation"; type="text/html"
Content-Type: application/json

Both headers are hints. They do not change how the endpoint behaves, and clients only benefit if something reads them, so also announce by email and in the docs.

What can be deprecated

• A whole API version, such as v1 in favour of v2.
• A single endpoint, for example one replaced by a new path.
• A request parameter or a response field, for example created replaced by created_at.
• An authentication method, such as API keys in favour of OAuth 2.0.
• A webhook event type or an SDK method.

Best practices

• Announce early. Give consumers enough time to schedule the work. There is no universal number: GitHub, for one, supports a previous REST API version for at least 24 months after a new one ships.
• Document the migration path. Show old to new mapping with code samples, not just "use the new API".
• Use the headers and a changelog. Make the change findable by machines and by people.
• Contact consumers directly. Email account owners and show an in-product notice. Few people read a blog.
• Track who still calls the old version. Log usage per endpoint and per consumer (API key, OAuth client) so you can reach the right people.
• Ship the replacement first. Run old and new side by side and keep SDKs in step.
• Rehearse the removal. A short, announced brownout, where the old version fails for a while, flushes out forgotten clients before the real cut-off.
• Return 410 Gone after sunset. MDN describes it as the resource being no longer available, and likely permanently. Use 404 when you do not know whether it is permanent.

Common mistakes

• Silent removal. No notice, angry customers.
• No migration guide. Consumers are left to reverse-engineer the difference.
• A window shorter than your customers' release cycle. Teams that ship quarterly cannot move in a few weeks.
• Removing a field that is still used. Check usage first.
• Forgetting SDKs and docs. They keep sending people to the old version.
• Deprecating without a replacement. Consumers have nowhere to go.
• Announcing only on a blog. Add headers, email and in-product notices.

Examples from real APIs

GitHub REST API. Versions are named by date and chosen with the X-GitHub-Api-Version header. Requests without it use 2022-11-28, and when a new version is released the previous one stays supported for at least 24 months (GitHub docs).

GitHub GraphQL API. GitHub announces breaking schema changes at least three months ahead and applies them on the first day of a quarter. Upcoming removals are listed on its breaking-changes page (GitHub docs).

Stripe. Requests use the account's default API version unless you override it with the Stripe-Version header, so you upgrade when ready. Since the 2024-09-30 release Stripe ships monthly versions without breaking changes and a major release with breaking changes twice a year (Stripe docs).

Testing and monitoring during a deprecation window

While two versions run side by side, check both. API tests that compare old and new responses catch behaviour drift before consumers do, and the guide to importing cURL, HAR, Postman and OpenAPI shows how to turn existing requests into load tests. LoadFocus API monitoring can run a check per endpoint and version, assert on status code, headers and body, and alert you if the replacement starts failing or slowing down. Free checks run every 5 minutes.

Also load test the new version at the combined traffic of both, because that is what it will carry after sunset. LoadFocus load testing runs JMeter and k6 scripts for that.

FAQ: API deprecation

How long should a sunset window be?

It depends on who your consumers are. Public APIs used by many teams need more time than an internal API with a few known clients. GitHub, for example, supports a previous REST API version for at least 24 months. Measure how long your slowest consumers need and add margin.

What is the difference between deprecation and sunset?

Deprecation is the announcement: it still works, but do not build on it. Sunset is the date it stops working.

Should I version my API?

Yes, if anyone outside your team depends on it. URL versions such as /v1/ are the simplest to see and test. Header or date-based versions, as GitHub and Stripe use, keep URLs stable but are easier to get wrong.

Which HTTP status should a sunset endpoint return?

410 Gone is the clearest. MDN notes that clients should not repeat requests to a 410, and that 404 is the choice when you do not know whether the removal is permanent.

How do I find out who still calls a deprecated endpoint?

Log each request with a consumer identifier such as the API key or OAuth client ID, then count calls per consumer per day. Contact the heaviest users first.

Is adding a field a breaking change?

Usually not, which is why additive changes rarely need deprecation. Removing a field, renaming it or changing its meaning does.