弃用和终止标头

弃用信息会告知客户端它刚刚调用的端点已被弃用——它仍然有效，但不应再使用。日落信息则会给出端点停止响应的日期。这些信息与指向替代端点的 Link 标头结合使用，使得 API 可以在流量本身中发布弃用声明，以便客户端代码能够注意到。

工作原理

客户端和网关可以在出现任一标头时记录日志或发出警报，以便团队在仍有时间时了解其依赖于即将停用的端点。日落标头包含一个 HTTP 日期。带有 rel="successor-version" 或 rel="deprecation" 的 Link 标头指向替代端点或迁移文档。

误解

在变更日志中添加弃用通知就足够了。没人会去阅读他们调用的每个 API 的变更日志；响应头会直接传递给实际受影响的代码，一旦这些通知出现，任何验证它们是否存在的测试都会失败。

点击这里试试

GET /friends/v1/characters返回带有 Deprecation、Sunset 和指向 v2 端点的 Link 标头的响应；在 Expectations 编辑器中断言它们，并使用 headers.deprecation exists。

相关内容

• API 版本控制
• HTTP 标头

资料来源

• HTTP semantics — RFC 9110
• OpenAPI Initiative

其他术语

• API 版本控制 — 并行运行多个版本的 API，因此重大变更不会破坏现有客户端。
• HTTP 标头 — 每个请求和响应都会发送名称-值元数据，与请求体分开。

阅读英文版

所有术语 · 测试技巧 · 全部 39 个模拟 REST API

最后更新时间 2026年10月16日