HTTP API 的结构化错误消息

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

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

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

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

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

问题

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

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

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

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

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

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

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

1. 提供跨提供商的统一性
2. 提高 API 稳定性

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

结构如下：

RFC 描述了以下字段：

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

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

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

一个例子

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

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

HTTP/1.1 429 Too Many Requests Date: Fri, 28 Oct 2022 11:56:11 GMT Content-Type: text/plain; charset=utf-8 Transfer-Encoding: chunked Connection: keep-alive Server: 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 实现者来说是一个巨大的帮助，因为它提供了快速指南以避免在每个项目中重新发明轮子。