API deprecation checklist: impact analysis before you remove an endpoint

The checklist#

1. 1

   Identify candidates

   Endpoints with few or no static callers and low traffic are starting points, not proof.

2. 2

   Find consumers

   Use code search, contract tracing, and runtime metrics. Include consumers outside your repositories.

3. 3

   Decide the replacement and window

   Write down the migration path, the window, and the owners.

4. 4

   Mark it deprecated

   Mark the operation as deprecated in the OpenAPI document. Send the Deprecation response header (RFC 9745) and, when you have a date, the Sunset header (RFC 8594), with a link to migration notes.

5. 5

   Watch traffic during the window

   Requests still arriving mean someone has not migrated.

6. 6

   Remove in a separate pull request

   Review that pull request's impact report and its coverage gaps.

7. 7

   Keep a record

   Note what evidence you reviewed and when.

Where Impact Gate fits#

Impact Gate lists deprecation candidates from static callers and imported Prometheus or Datadog evidence, lets an owner record an evidence review for a specific snapshot, and shows coverage gaps. A review does not approve a production removal.

Common questions#

What is the difference between the Deprecation and Sunset headers? Deprecation says a resource is or will be deprecated. Sunset gives the date it is expected to stop responding.

How long should the window be? It depends on your consumers. Agree it with them; there is no universal number.