API Deprecation
The warning period before an API is removed, giving callers a replacement, migration guide, deadline, and time to move.
See it
What it is
API deprecation marks an endpoint or version as still working but no longer recommended, with a replacement path and a removal date. It is the warning period between 'we want callers off v1' and actually turning v1 off. Documentation, changelogs, direct notices, and response headers should all tell the same story.
Reach for it before any breaking removal. Mark the operation deprecated in OpenAPI, publish a migration guide with old and new examples, and use traffic logs to identify callers that remain. RFC 9745 defines the Deprecation response header, while RFC 8594 defines Sunset for the time a resource is expected to become unavailable.
Deprecation is not deletion, and a date in a blog post does not move clients by itself. Some callers are batch jobs nobody watches, mobile apps that update slowly, or customers pinned to an old SDK. Measure use by client and version, contact owners repeatedly, freeze new adoption, and rehearse the shutdown. If the replacement cannot perform the old job, the migration window has not really started.
Ask AI for it
Deprecate GET /v1/reports without removing it yet. Mark the operation deprecated: true in OpenAPI 3.1, add the RFC 9745 Deprecation header, add an RFC 8594 Sunset header with the retirement date, and include a Link header to a migration guide for GET /v2/reports. Log client ID, SDK version, and route usage; build a dashboard of remaining callers; block new API keys from adopting v1; and add contract tests proving v1 keeps its old behavior through the sunset date. Produce the migration guide with side-by-side requests, responses, and changed error codes.