API Deprecation Checklist
An API deprecation checklist for retiring an endpoint or API version: measure usage, announce a sunset date, add headers, help clients migrate, then switch off.
- Typical schedule per deprecated endpoint or API version
- The checklist 5 sections, 19 items
- Variables
{{api_endpoint}}{{replacement}}{{sunset_date}}
Use this checklist when you retire a public or partner-facing API endpoint, field or whole API version. Deprecation is a process that runs over weeks or months, not a single change. You announce it, make it visible in the API itself, help clients move to the replacement, and only then switch the old endpoint off. Starting a run when the decision is made keeps the dates and the customer contacts in one place.
Who owns it
The team that owns the API owns the run, with one named engineer or product manager as the contact. Customer success or support owns the outreach to affected customers. The final switch-off should be approved by the owner after checking usage again.
Common pitfalls
- Not knowing who uses it. Without usage data per client or API key, you cannot warn the right people. Add usage tracking before you announce anything.
- Announcing only in the changelog. Most API clients do not read it. Use email to the technical contacts, a note in your developer docs, and signals in the API responses.
- A deadline that is too short. Clients have their own release cycles. Give them enough time and publish the date, then keep it.
- Switching off without a brownout. A short, announced period where the old endpoint returns errors shows who is still using it, while you can still turn it back on.
- No replacement. Deprecating an endpoint without an equal or better replacement drives customers away. Ship and document the replacement first.
The checklist: Deprecate {{api_endpoint}} (sunset {{sunset_date}})
Decide
-
Reason for deprecating
{{api_endpoint}}is documented -
Replacement
{{replacement}}is live, documented and covers the same use cases -
Usage of
{{api_endpoint}}is measured per client, API key or organisation -
Sunset date
{{sunset_date}}is set and agreed with product, support and salesCheck contracts or published API policies for promised notice periods.
Announce
-
Developer docs mark
{{api_endpoint}}as deprecated with the sunset date and a link to{{replacement}} -
Migration guide from
{{api_endpoint}}to{{replacement}}is published with examples -
Technical contacts of all active clients are notified by email
-
Changelog and API status page announce the deprecation optional
-
OpenAPI specification marks the operation or field as deprecated
Signal in the API
-
Responses from
{{api_endpoint}}include Deprecation and Sunset headersThe Sunset header is defined in RFC 8594. Add a Link header that points to the migration guide.
-
Calls to
{{api_endpoint}}are logged so remaining users can be identified -
SDKs and client libraries show a deprecation warning in a new release optional
Migrate clients
-
Usage is reviewed regularly and clients still calling
{{api_endpoint}}are contacted directly -
Reminder is sent to remaining clients ahead of
{{sunset_date}} -
Planned brownout periods are announced and run before the sunset date optional
Switch off
-
Usage is checked one last time and the owner approves the switch-off
-
{{api_endpoint}}returns a clear error, such as 410 Gone, with a link to the migration guide -
Code, tests and docs for
{{api_endpoint}}are removed after a short grace period -
Support is briefed on how to help clients that still hit the old endpoint
Checklist as Markdown
Frequently asked questions
How much notice should I give before removing an API?
Enough for your clients to plan, build and release the change, which depends on who they are. Partners with slow release cycles need much more time than internal teams. Check what your terms or API policy promise, publish the date, and avoid moving it earlier once announced.
What HTTP status should a removed endpoint return?
410 Gone is the clearest signal that a resource was removed on purpose. Include a response body that explains the change and links to the migration guide. Some teams return 404 for removed endpoints, which works but tells the client less.
What is the difference between API deprecation and API versioning?
Versioning is how you introduce breaking changes without breaking existing clients, for example with a new version in the path or a header. Deprecation is how you retire an old version or endpoint once a replacement exists. A clear versioning policy makes each deprecation easier, because clients know what to expect.
Updated