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

Question

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

Bla*_*rog 75 rest http http-status-codes deprecation-warning

我正在升级我们的REST API端点,并且我想在他们调用要弃用的端点时通知客户端.
我应该在响应中使用哪个标头,并显示"此API版本已被弃用,请参阅最新文档以更新您的终端"的消息

Answer 1

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

Warning: 299 - "Deprecated API"

Run Code Online (Sandbox Code Playgroud)

您还可以使用发出警告的"代理"指定" - ",并在警告文本中更明确:

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

Run Code Online (Sandbox Code Playgroud)

警告标题在此处指定:https://tools.ietf.org/html/rfc7234#section-5.5.Warn-code 299是通用的,"Deprecated"不是标准的.

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

我从来没有使用它,但是当我的公司在Rest API中更成熟时,我会整合它.

请注意，HTTP 警告本身[已被弃用](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Warning) (2认同)

Answer 2

Ema*_*sev 34

你可以使用410(Gone).

以下是W3C的状态代码定义如何描述它:

410(已走)

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

410响应主要用于通过通知接收方资源是故意不可用的以及服务器所有者希望移除到该资源的远程链接来辅助web维护的任务.这种事件对于限时,促销服务以及属于不再在服务器站点工作的个人的资源是常见的.没有必要将所有永久不可用的资源标记为"已消失"或将标记保留任何时间长度 - 这由服务器所有者自行决定.

410的问题在于它与"待弃用"要求不匹配......当API消失时,它可以正常工作,但不会*在*future*中消失. (33认同)
"410 Gone"不是关于弃用,而是关于可用方法的更多信息.正如@BenC所说,更好的方法是使用[警告标题](https://tools.ietf.org/html/rfc7234#section-5.5) (4认同)
如果返回410,则会破坏向后兼容性 (3认同)
这可能是已弃用 API 的下一阶段 (3认同)

Answer 3

u07*_*7ch 14

我会和301一起去(永久移动)300系列代码应该告诉客户他们有行动要做.

这可能是我在实际删除端点后会使用的,但我想让他们有机会在一段时间内得到通知(假设他们将查看响应中的HTTP头),以便他们可以进行必要的更改他们的结局. (4认同)
搬家没有真正的地位.302(请求的资源暂时驻留在另一个位置,但仍可以在请求的URI处找到它.)... (2认同)
我不是在寻找状态，而是在寻找要添加到响应中的“标准”标头。 (2认同)

Answer 4

小智 7

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

Answer 5

typ*_*ror 6

我建议一个207 Multi-Status响应,表明它是一个成功的响应,但它也可能有第二个被弃用的状态.

有趣的。我不知道那个，但我认为在实践中存在很大的危险，即使它仍在 200 范围内，您也会通过交换到不同的响应代码来为 _some_ 客户端引入破坏性更改。我想你可能会温和地增加压力。以`Deprecation` 头开始（不幸的是，客户可能会忽略）然后使用这个 207 代码，然后 301 移动，最后 410 消失了！ (2认同)

Answer 6

小智 6

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

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

要通知用户已弃用资源的计划停用日期，Sunset除了 Deprecation 标头之外，还应使用标头。这在第 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。

归档时间：	13 年，1 月前
查看次数：	25485 次
最近记录：	6 年，9 月前