97

我正在升级我们的 REST API 端点，并且我想在客户端调用将被弃用的端点时通知他们。
我应该在响应中使用什么标头，并带有类似于“此 API 版本已被弃用，请查阅最新文档以更新您的端点”的消息

4

6 回答 6

79

我不会更改状态代码中的任何内容以向后兼容。我会在响应中添加一个“警告”标题：

Warning: 299 - "Deprecated API"

您还可以在发出警告的“代理”中指定“-”，并在警告文本中更明确：

Warning: 299 api.blazingFrog.com "Deprecated API: use betterapi.blazingFrog.com instead. Old API maintained until 2015-06-02"

此处指定了警告标头：https ://www.rfc-editor.org/rfc/rfc7234#section-5.5 。警告代码 299 是通用的，“已弃用”不是标准的。

您必须告诉您的 API 客户端记录 HTTP 警告并对其进行监控。

直到现在我才使用它，但是当我的公司在 Rest API 方面更加成熟时，我会集成它。

编辑（2019-04-25）：正如@Harry Wood 提到的那样，警告标头位于文档中与缓存相关的一章中。但是，RFC 很明确Warnings can be used for other purposes, both cache-related and otherwise.

如果您更喜欢替代方法，此草案https://datatracker.ietf.org/doc/html/draft-dalal-deprecation-header-00建议使用新标题“弃用”。

编辑（2021-01-04）：正如@Dima Parzhitsky 提到的那样，MDN 说这个标头已被弃用

于 2015-04-14T09:29:16.470 回答
42

您可以使用410 (Gone)。

以下是 W3C 的状态代码定义对它的描述：

410（消失）

请求的资源在服务器上不再可用，并且不知道转发地址。预计这种情况将被视为永久性的。具有链接编辑能力的客户端应该在用户批准后删除对 Request-URI 的引用。如果服务器不知道或无法确定条件是否是永久的，则应该使用状态代码 404（未找到）。除非另有说明，否则此响应是可缓存的。

410 响应的主要目的是通过通知接收者该资源故意不可用并且服务器所有者希望删除到该资源的远程链接来协助 Web 维护任务。这种事件对于限时促销服务和属于不再在服务器站点工作的个人的资源很常见。不必将所有永久不可用的资源标记为“已消失”或将标记保留任意时间——这由服务器所有者自行决定。

于 2013-03-01T15:17:24.687 回答
16

我会/已经选择301（永久移动） 300 系列代码应该告诉客户他们有行动要做。

于 2012-12-14T18:20:47.547 回答
7

完善@dret 的回复。有两个相关的 HTTP 标头用于弃用：( Deprecationhttps://datatracker.ietf.org/doc/html/draft-dalal-deprecation-header-00 )和Sunset.

要通知用户计划的弃用，Deprecation应使用 HTTP 标头。这表明端点将在未来某个时间被丢弃。它还允许您指明发布日期，并描述替代资源。

为了通知用户已弃用资源的计划日落日期，Sunset除了 Deprecation 标头之外，还应使用标头。这在第 #5 节https://datatracker.ietf.org/doc/html/draft-dalal-deprecation-header-00#section-5中进行了描述。

标题草案 #11 https://datatracker.ietf.org/doc/html/draft-wilde-sunset-header-11在第 1.4 节https://datatracker.ietf.org/doc/htmlSunset中也阐明了这一方面/draft-wilde-sunset-header-11#section-1.4。

于 2019-03-25T16:45:23.213 回答
6

我会推荐一个207 Multi-Status响应，表明它是一个成功的响应，但它也可能具有第二个弃用状态。

于 2017-03-16T21:14:23.970 回答
5

有一个名为的 HTTP 标头字段Sunset旨在表示即将弃用的资源。https://datatracker.ietf.org/doc/html/draft-wilde-sunset-header正处于成为 RFC 的最后阶段。理想情况下，您的 API 应该记录它将要使用Sunset的 ，以便客户可以查找它并根据需要采取行动。

于 2019-01-15T00:20:58.783 回答