logo标签列表

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

resthttphttp-status-codesdeprecation-warning
110

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

你应该在响应中使用 "Warning" 头部，并在其中加入类似于以下内容的消息："299 - This API version is being deprecated, please consult the latest documentation to update your endpoints"。

6个回答
90

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

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。Warn-code 299是通用的，“弃用”不是标准。

您需要告诉您的API客户端记录HTTP警告并监视它。

我现在从未使用过它，但当我的公司在Rest API方面更加成熟时，我会将其集成。

编辑（2019-04-25）：正如@Harry Wood所提到的，警告头在文档中与缓存相关的章节中。然而，RFC明确指出“警告可以用于其他目的，包括与缓存有关和其他方面。”

如果您喜欢另一种方法，则此草案https://datatracker.ietf.org/doc/html/draft-dalal-deprecation-header-00建议使用新的标题“Deprecation”。

编辑（2021-01-04）：正如@Dima Parzhitsky所提到的，MDN表示此标题已弃用

1
在这里，警告值末尾的警告日期没有任何作用，最好省略它，否则您会冒着让客户感到困惑的风险：“如果收件人收到与同一消息中的“日期”值不同的警告日期，则收件人必须在使用该消息之前排除警告值。” - Vasiliy Faronov
如果您包含了warn-date，它必须与Date头部以相同的格式进行格式化："Thu, 02 Apr 2015 12:25:32 GMT"。 - Vasiliy Faronov
@VasiliyFaronov：你是正确的，因为在这种情况下（弃用的API），此警告消息将来将始终为真。因此，如果响应（带有警告消息）由代理中的缓存发送，并且消息日期不同，则会忽略警告，而它仍将有效。我编辑了响应。 - BenC
1
"警告"标题并不仅与缓存有关。在“警告”部分的第一句话是：“警告可以用于其他目的，包括与缓存有关和其他方面。” - Çelebi Murat
5
请注意，HTTP警告本身现在正在被弃用。 - Parzh from Ukraine
显示剩余2条评论
51
你可以使用410（已经消失）。
以下是W3C的状态码定义对它的描述：

410（已经消失）

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

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

53
410的问题在于它不符合“即将弃用”的要求......当API消失时，它可以正常工作，但不能应对在未来它将会消失的情况。 - Julien Genestoux
4
如果您返回410，将会破坏您的向后兼容性。 - BenC
6
“410 Gone”并不是指某个服务已经被废弃，而是指该服务的某些方法不再可用。就像@BenC所说，更好的做法是使用“Warning header”。（注：此处提供了RFC7234中第5.5节的链接） - sempasha
3
这可能是弃用API的下一个阶段。 - Shiplu Mokaddim
18

我会选择301（永久重定向）。300系列状态码的目的是告诉客户端它们需要执行一个操作。

7
一旦端点实际被移除，我可能会使用这个，但我想给他们一些时间来接收通知（假设他们将查看响应中的HTTP标头），以便他们可以在自己的端进行必要的更改。 - BlazingFrog
2
没有真正的“去移动”状态。302（所请求的资源暂时驻留在另一个位置，但仍可在所请求的URI找到）。... - u07ch
2
我不是在寻找状态，而是要添加一个“标准”头部到响应中。 - BlazingFrog
1
这种类型的响应没有标准头。您应该创建自己的头，并在您自己的API文档中进行描述。 - Brian Kelly
1
状态码是REST API的一部分。由于API是客户端和服务之间的协议，因此首先应该警告客户端未来可能会发生的破坏性变化。有些客户端可能不支持重定向，因此在收到“301永久移动”后，他们将认为请求失败了，因为响应代码未知（例如，他们期望“200成功”）。换句话说，通过更改响应的状态码，您可能会破坏与客户端的兼容性。正如@BenC所说，更好的方法是使用警告标头来通知客户端。 - sempasha
显示剩余2条评论
14

对 @dret 的回答进行澄清。与弃用相关的有两个HTTP头：Deprecation（https://datatracker.ietf.org/doc/html/draft-dalal-deprecation-header-00）和Sunset。

为了通知用户计划弃用的信息，应使用Deprecation HTTP头。这表示将来某个时间点该端点将被删除。它还允许您指示宣布此事的日期，并描述备选资源。

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

Sunset头草案11 https://datatracker.ietf.org/doc/html/draft-wilde-sunset-header-11 在第1.4节中也澄清了这方面的问题：https://datatracker.ietf.org/doc/html/draft-wilde-sunset-header-11#section-1.4。

7
我建议使用207多状态响应，表明它是一个成功的响应，但也有可能具有第二个被弃用的状态。
2
有趣。我不知道那个，但是我认为在实践中，即使仍然在200范围内，通过切换到不同的响应代码，您很可能会为某些客户引入破坏性更改的风险。我想你可以逐渐增加压力。首先使用“Deprecation”标头（客户端可能会忽略不幸的是），然后使用此207代码，然后301移动，最后410消失！ - Harry Wood
7
网页内容由stack overflow 提供, 点击上面的
可以查看英文原文，
原文链接