每日分享最新，最流行的软件开发知识与最新行业趋势，希望大家能够一键三连，多多支持，跪求关注，点赞，留言。

RFC 7807 不仅可以帮助客户端开发人员。这对 API 实现者来说是一个巨大的帮助，因为它提供了快速指南以避免在每个项目中重新发明轮子。

自从我开始从事 Apache APISIX 项目以来，我一直在努力提高我对REST RESTful HTTP API 的知识和理解。为此，我正在阅读和观看以下来源：

• 书籍：目前，我正在完成API 设计模式。期待很快的审查。
• YouTube：我推荐Erik Wilde 的频道。虽然有些视频比其他视频更好，但它们都专注于 API。
• IETF RFC ：大多数 RFC与API 无关，而是由一个友好的人编制了一个列表，其中列出了.

今天，我想介绍“HTTP API 的问题详细信息”RFC，又名RFC 7807。

问题

REST 原则要求使用 HTTP 状态进行通信。对于错误，HTTP 定义了两个范围：客户端错误4xx，和服务器错误，5xx。

想象一个允许您进行转账的银行 API。如果您尝试将更多资金转入您的帐户，它应该会失败。几个 HTTP 状态代码可以适合：

• 400 Bad Request：由于被认为是客户端错误，服务器无法或不会处理请求。
• 402 Payment Required：在客户付款之前无法处理请求。但是，不存在标准的使用约定，不同的实体在其他上下文中使用它。
• 409 Conflict：请求与目标资源的当前状态冲突。

这是第一个问题：HTTP 状态代码是为通过浏览器的人机交互指定的，而不是为通过 API 的机器对机器交互指定的。因此，选择一个与用例一对一映射的状态代码很少是简单的。作为记录，在我们的案例中，Martin Fowler 似乎更喜欢 409。

无论状态码是什么，第二个问题都与错误有效载荷有关，或者更准确地说，与它的结构有关。如果单个组织管理客户端和 API 提供者，则结构并不重要。即使有一个专门的团队开发它们中的每一个，它们也可以保持一致。例如，想象一个调用自己的 API 的移动应用程序。

但是，当团队决定使用第三方 API 时，就会出现问题。在这种情况下，响应结构的选择很重要，因为它现在被视为合同的一部分：提供者的任何更改都可能破坏客户端。更糟糕的是，结构可能因供应商而异。

因此，标准化的错误报告结构：

• 提供跨提供商的统一性
• 提高 API 稳定性

RFC 7807

RFC 7807 旨在通过提供标准化的错误结构来解决该问题。

结构如下：

RFC 描述了以下字段：

• "type"( ) -标识问题类型string的 URI 参考[RFC3986] ；本规范鼓励在取消引用时为问题类型提供人类可读的文档（例如，使用 HTML [W3C.REC-html5-20141028]）。当此成员不存在时，假定其值为"about:blank"。
• "title"( string) - 问题类型的简短易读摘要；除了本地化的目的（例如，使用主动内容协商；参见[RFC7231，第 3.4 节]），它不应该随着问题的发生而改变。
• "status"( number) - 由源服务器生成的（[RFC7231]，第 6 节）用于此问题的发生。
• "detail"( string) - 针对此问题发生的特定于人类可读的解释
• "instance"( string) - 标识特定问题发生的 URI 引用。如果取消引用，它可能会或可能不会产生更多信息。

--问题详细信息对象的成员

当需要更多资金进行银行转账时，RFC 提供了以下示例。

一个例子

我将使用我现有的演示之一作为示例。该演示重点介绍了简化 API 演进过程的几个步骤。

在第 6 步中，我希望用户注册，因此如果他们未通过身份验证，我会限制时间窗口内的调用次数。我为此创建了一个专用的 Apache APISIX 插件。调用次数达到限制后，返回：

HTTP/1.1 429 Too Many RequestsDate: Fri, 28 Oct 2022 11:56:11 GMTContent-Type: text/plain; charset=utf-8Transfer-Encoding: chunkedConnection: keep-aliveServer: APISIX/2.15.0{"error_msg":"Please register at https:\/\/apisix.org\/register to get your API token and enjoy unlimited calls"}

让我们按照 RFC 7807 构建消息。

结论

RFC 7807 不仅可以帮助客户端开发人员。这对 API 实现者来说是一个巨大的帮助，因为它提供了快速指南以避免在每个项目中重新发明轮子。