API Deprecation 与 Sunset 指南

概述

在 API 生命周期中，可能需要逐步淘汰某个 API 端点、API 版本或特定 API 功能。

常见情况包括：

• 移除不再支持的字段或参数
• 使用新的设计替换现有 API 端点
• 关闭过时的业务功能

只要仍有现有消费者使用这些 API 或功能，直接移除就属于破坏性变更，不能在没有充分沟通和迁移流程的情况下执行。

为了给 API 消费者留出足够的适应时间，API 提供方应定义并公布：

• Deprecation date
• Sunset date

Deprecation 和 Sunset 流程应主要通过标准沟通渠道公布，例如：

• API 文档
• Release notes
• 服务协议
• 客户通知

HTTP Header 和 API Specification 应作为额外的技术沟通机制，而不能作为唯一的通知方式。

Deprecation 与 Sunset 的区别

Deprecation

Deprecation date 表示 API 功能进入有限支持阶段的时间点。

进入 Deprecation 阶段后：

• API 功能仍然可用
• 现有客户端可以继续使用，不需要立即修改
• 不再新增功能
• 不建议在新的集成中继续使用该功能
• 消费者应开始规划迁移

Deprecation 本身不是向后不兼容的变更。

示例：

Deprecation date: 2026-01-01

The API remains functional, but users are expected to migrate to the replacement API.

Sunset

Sunset date 表示 API 功能将被永久移除的时间点。

进入 Sunset 阶段后：

• API 端点或功能不再可用
• 继续使用已移除功能的现有客户端将调用失败
• 消费者必须在该日期前完成迁移

Sunset 属于破坏性变更。

示例：

Sunset date: 2027-01-01

The API endpoint will no longer be accessible after this date.

Deprecation 和 Sunset 之间必须留出足够的迁移时间。

Deprecation 生命周期

阶段 1：API 功能进入 Deprecation

示例：

Deprecation date: 2026-12-31

必须执行：

• 在 API Specification 中将该功能标记为 deprecated
• 如果存在替代方案，说明替代 API 或迁移方式
• 开始返回 Deprecation HTTP Header

示例：

Deprecation: Thu, 31 Dec 2026 23:59:59 GMT

阶段 2：宣布 API Sunset

示例：

Sunset date: 2027-12-31

必须执行：

• 在 API Specification 中记录 Sunset date
• 开始返回 Sunset HTTP Header
• 继续返回 Deprecation Header

示例：

Deprecation: Thu, 31 Dec 2026 23:59:59 GMT
Sunset: Fri, 31 Dec 2027 23:59:59 GMT

阶段 3：移除 API 功能

到达 Sunset date 后：

必须执行：

• 从 API Specification 中移除已 Deprecation 的资源
• 拒绝针对已移除资源的请求

推荐的 HTTP 响应：

HTTP/1.1 410 Gone

410 Gone 表示该资源过去存在，但现在已永久不可用。

Deprecation 周期的合作伙伴协议

当 API 被外部合作伙伴使用时，API 提供方必须在宣布 Deprecation 后定义合理的维护周期。

外部消费者应就以下内容达成一致：

• Deprecation 之后的最短支持周期
• 预期迁移时间表
• Sunset 计划

该协议应在消费者开始使用 API 之前完成。

目标是确保 API 变得不可用之前，消费者拥有足够的迁移时间。

在 OpenAPI Specification 中反映 Deprecation

API Deprecation 信息必须包含在 OpenAPI Specification 中。

以下 API 元素可以标记为 deprecated：

• API 端点
• Operations
• Parameters
• Request/response schemas
• Schema properties

受影响的元素应使用：

deprecated: true

示例：

paths:
  /customers:
    get:
      deprecated: true
      description: >
        This endpoint is deprecated.
        Use /customer-profiles instead.

补充文档还应说明：

• 该功能为什么进入 Deprecation
• 应使用什么替代方案
• 消费者应如何迁移
• 计划中的 Sunset date

示例：

description: >
  This field is deprecated.
  Use "customerName" instead.
  This field will be removed after 2027-01-01.

Deprecation 和 Sunset HTTP Header

在 Deprecation 期间，API 提供方应在 HTTP 响应中包含 Deprecation 信息。

推荐 Header：

Deprecation: <date-time>
Sunset: <date-time>

示例：

HTTP/1.1 200 OK

Deprecation: Thu, 31 Dec 2026 23:59:59 GMT
Sunset: Fri, 31 Dec 2027 23:59:59 GMT

Deprecation Header

Deprecation Header 表示某个 API 功能不再建议用于新的调用场景。

它可以包含：

• 表示 Deprecation 开始时间的时间戳
• 表示某项功能已经停止使用的布尔值

示例：

Deprecation: Thu, 31 Dec 2026 23:59:59 GMT

Sunset Header

Sunset Header 表示 API 功能停止提供服务的最终日期。

示例：

Sunset: Fri, 31 Dec 2027 23:59:59 GMT

Sunset date 应为消费者迁移到替代方案留出足够时间。

多个已 Deprecation 的功能

如果同一个响应中有多个 API 元素进入 Deprecation，Header 应表示相关日期中最早的日期。

示例：

Feature A sunset:
2027-12-31

Feature B sunset:
2027-06-30

响应应使用：

Sunset: Wed, 30 Jun 2027 23:59:59 GMT

因为它代表更短的迁移窗口。

客户端监控建议

API 消费者应监控与 Deprecation 相关的信息。

建议：

• 监控 Deprecation Header
• 监控 Sunset Header
• 为即将移除的 API 创建告警
• 在 Sunset date 之前规划迁移活动

示例：

If Sunset date is within 90 days:

-> Notify API owners
-> Start migration activities
-> Track migration progress

重要说明

Header 不能替代沟通

仅仅存在以下 Header：

Deprecation
Sunset

并不能替代与 API 消费者进行充分沟通。

API 提供方还应使用：

• API 文档
• Release notes
• Migration guides
• 客户沟通渠道

避免使用 Warning Header

一些系统过去使用 HTTP Warning Header 发送 Deprecation 通知。

但是：

• 它的语义不够明确
• 不适合 API 生命周期管理
• 现代 API 生命周期管理应使用专用的 Deprecation 和 Sunset Header

总结

良好的 API 退役流程应遵循以下原则：

清晰的 Deprecation 和 Sunset 策略可以在降低消费者影响的同时，支持 API 持续演进。