API Retirement Bench
API Deprecation Checklist for Retiring an Endpoint
Before retiring an API endpoint, inventory callers, give them a documented migration path, and replay representative requests against the replacement. Keep the endpoint available when unexplained traffic or failed migrations still make shutdown unsafe.
Worked example
| Synthetic fixture | Expected evidence | Gate |
|---|---|---|
| Known client A | Replay succeeds against replacement | Pass |
| Known client B | Replacement rejects a formerly valid input | Hold |
| Unidentified traffic | Owner or accepted mitigation is missing | Hold |
Keep the old endpoint available. Resolve the incompatible request and investigate unidentified traffic. Record the evidence, observation window and owner before revisiting retirement.
How to run the check
- Inventory known callers and report unknown traffic separately.
- Communicate the replacement, transition schedule and support route. Use Deprecation and Sunset response fields where applicable.
- Replay success and failure cases, then check actual usage against the shutdown gate and rehearse the rollback or mitigation path.
Set observation windows and residual-traffic thresholds with the service owner. The example uses synthetic clients and never calls a production endpoint.
What is the difference between Deprecation and Sunset?
Deprecation signals that a resource is or will be deprecated. Sunset can communicate when it is expected to become unavailable. Check RFC 9745 and RFC 8594 for the protocol details.
Reference: IETF RFC 9745 on the HTTP Deprecation header field