中文
devexamples
← Workflows

阅读中文版本

API Deprecation and Sunset Workflow

Announce a deprecation, emit sunset and deprecation headers, measure remaining usage, and remove the endpoint only after consumers migrate.

intermediate~90 minapilifecyclecommunication

Objective

Retire an API endpoint safely without breaking unknown consumers or silently failing them.

Environment

  • An API with telemetry per endpoint and consumer
  • A communication channel for announcements

Steps

1. Inventory consumers and current usage

Inventory consumers and current usage per endpoint.

Expected state: You know who still calls the endpoint and how much.

2. Announce the deprecation with dates

Announce the deprecation with dates and a migration guide.

Expected state: Consumers have a deadline and a path.

3. Emit Deprecation and Sunset headers

Emit Deprecation and Sunset headers and keep counting usage.

Expected state: Calls warn and usage trends down.

4. Sunset the endpoint when usage

Sunset the endpoint when usage is zero or the date passes.

Expected state: The endpoint is removed deliberately, not abruptly.

Decision points

What if a consumer misses the deadline?

  • Extend the sunset for that consumer
  • Remove it as scheduled

Extend only for named consumers with a documented exception and a hard new date.

Hard removal or gradual throttle?

  • Return 410 immediately
  • Throttle then remove

Throttle first can surface hidden consumers before the final cut.

Expected outcome

The deprecated endpoint is removed only after consumers have migrated or been explicitly notified, with a documented audit trail.

Verification

Confirm usage dropped to the agreed threshold before sunset, warn logs show the headers, and no consumer reports an unannounced break.

Cleanup

Archive the deprecation notice, usage reports, and the migration guide link.

Overview

Retire an API endpoint safely without breaking unknown consumers or silently failing them. Confirm usage dropped to the agreed threshold before sunset, warn logs show the headers, and no consumer reports an unannounced break.

Steps

  1. Inventory consumers and current usage per endpoint. Expected state: You know who still calls the endpoint and how much.
  2. Announce the deprecation with dates and a migration guide. Expected state: Consumers have a deadline and a path.
  3. Emit Deprecation and Sunset headers and keep counting usage. Expected state: Calls warn and usage trends down.
  4. Sunset the endpoint when usage is zero or the date passes. Expected state: The endpoint is removed deliberately, not abruptly.
HTTP/1.1 200 OK
Deprecation: @1735689600
Sunset: Wed, 01 Jan 2026 00:00:00 GMT
Link: <https://docs.example.com/migrate>; rel="deprecation"

Verification

  • The deprecated endpoint is removed only after consumers have migrated or been explicitly notified, with a documented audit trail.

Decision points

  • What if a consumer misses the deadline? Options: Extend the sunset for that consumer; Remove it as scheduled. Recommended: Extend only for named consumers with a documented exception and a hard new date.
  • Hard removal or gradual throttle? Options: Return 410 immediately; Throttle then remove. Recommended: Throttle first can surface hidden consumers before the final cut.