HTTP响应标头的约定，用于通知客户端已弃用的API

84

我正在升级REST API端点，并且我想在客户端调用不赞成使用的端点时通知它们。
我应在响应中使用什么标题，并带有一条消息，标题为“已弃用此API版本，请查阅最新文档以更新您的端点”

rest  http  http-status-codes  deprecation-warning 
— 炽热的青蛙
source

Answers:

72

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

Warning: 299 - "Deprecated API"

您还可以将发出警告的“ Agent”指定为“-”，并在warn-text中更加明确：

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

在此处指定警告标头：https : //tools.ietf.org/html/rfc7234#section-5.5。警告代码299是通用的，“不赞成使用”不是标准的。

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

到目前为止，我从未使用过它，但是当我的公司在Rest API中变得更加成熟时，我将对其进行集成。

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

如果您喜欢其他方法，则此草稿https://tools.ietf.org/html/draft-dalal-deprecation-header-00建议使用新的标头“ Deprecation”。

— BenC
source
1
警告值末尾的警告日期在此无用，最好将其省略，否则您可能会使客户感到困惑：。。如果收到的警告日期Date与同一条消息中的值不同，则接收者必须排除警告值。。。之前。。。使用消息。”
— Vasiliy Faronov '16
如果您确实包含警告日期，则其格式必须与Date标头相同："Thu, 02 Apr 2015 12:25:32 GMT"。
— Vasiliy Faronov，
@VasiliyFaronov：您是对的，因为在这种情况下（已弃用的API），该警告消息将来将始终为真。因此，如果响应（带有警告消息）是由代理中的缓存发送的，并且消息日期不同，则警告将被忽略，而警告仍然有效。我编辑回复
— BenC
但是，“警告”标头不是与缓存相关吗？我的意思是在您的文档链接中它提到了缓存，但是整个RFC文档似乎都与缓存有关。但是Warning标头确实可以很好地用作描述过时的自由文本位置。其他答案中提到的Deprecation和Sunset标头似乎是一种新兴的标准解决方案，用于以更严格的，更可能是机器可读的方式描述过时问题。
— 哈里·伍德
1
Warning标头不只与缓存有关。本Warning节中的第一句话是“警告可以用于与缓存相关或其他目的的其他目的。”
— 切莱比穆拉特
37

您可以使用410（Gone）。

这是W3C的状态代码定义对其进行描述的方式：

410（已去）

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

410响应主要用于通过通知接收者资源有意不可用以及服务器所有者希望删除指向该资源的远程链接来辅助Web维护任务。对于限时促销服务和属于不再在服务器站点工作的个人的资源而言，此类事件很常见。不必将所有永久不可用的资源标记为“已消失”，也不必将标记保留任何时间长度-服务器所有者可以自行决定。

— 伊曼纽尔·鲁塞夫（Emanuil Rusev）
source
35
与410的问题是，它不匹配“要被弃用”的要求......它工作正常时，API走了，但不是说它会在消失的未来。
— Julien Genestoux 2014年
3
如果返回410，则将破坏向后兼容性
— BenC
4
410 Gone这与弃用无关，而与不再可用的方法有关。正如@BenC所说，更好的方法是使用警告标头
— sempasha，2016年
2
这可能是不推荐使用的API的下一阶段
— Shiplu Mokaddim，
16

我本想/已经放弃了301（永久移动）300系列代码应该告诉客户他们有行动要做。

— u07ch
source
4
这实际上是在端点被删除后我将要使用的功能，但是我想给他们一个机会在一段时间内得到通知（假设他们将在响应中查看HTTP标头），以便他们可以在上进行必要的更改他们的结局。
— BlazingFrog 2012年
2
确实没有一个可以动的地位。302（请求的资源临时位于另一个位置，但仍可以在请求的URI上找到它。）...
— u07ch
1
我不是在寻找状态，而是在寻找要添加到响应的“标准”标头。
— 火焰蛙
1
没有这种响应的标准标头。您应该创建自己的标头，并在自己的api文档中对其进行描述。
— 布莱恩·凯利
我认为任何响应代码> = 300都应该导致问题。299允许客户端在进行必要的更改之前使应用程序保持活动状态，直到禁用API。
— devlord
6

我建议您提供一个207 Multi-Status响应，表明它是成功的响应，但它也可能具有第二个已过时的状态。

— 打字错误
source
1
有趣。我对此一无所知，但我认为在实践中存在很大的危险，即使交换器的响应代码仍在200范围之内，您也可能会通过交换不同的响应代码来为某些客户引入重大变更。我想您可能会逐渐缓解压力。从Deprecation标头开始（不幸的是，客户端可能会忽略该标头），然后再使用此207代码，然后再移动301，最后再消失410！
— 哈里·伍德
4

完善@dret的响应。有两个相关的HTTP标头用于弃用：Deprecation（https://tools.ietf.org/html/draft-dalal-deprecation-header-00）和Sunset。

要通知用户计划中的弃用，Deprecation应使用HTTP标头。这表明该端点将在将来的某个时间删除。它还允许您指出宣布日期，并描述其他资源。

要通知用户有关已弃用资源的计划停用日期，Sunset除“弃用”标头外，还应使用该标头。这在第5节https://tools.ietf.org/html/draft-dalal-deprecation-header-00#section-5中进行了描述。

草案＃11 https://tools.ietf.org/html/draft-wilde-sunset-header-11所述的Sunset报头阐明这一方面以及第1.4节https://tools.ietf.org/html/draft-wilde -sunset-header-11＃section-1.4。

— sdatspun2
source
By using our site, you acknowledge that you have read and understand our Cookie Policy and Privacy Policy.
Licensed under cc by-sa 3.0 with attribution required.