API 请求失败后发生了什么？( 二 )

2022-04-24 API

这些 RFC 为此定义了两种新的对应内容类型：Application/problem+json或application/problem+xml 。返回错误的 HTTP 响应应在其Content-Type响应标头中包含适当的内容类型，并且客户端可以检查该标头以确认格式。
这个示例包括规范定义的一些标准化字段。完整列表是如下：

type：标识错误类型的 URI 。在浏览器中加载这个 URI 应该转向这个错误的文档，但这不是严格要求的。此字段可用于识别错误类。理论上讲，将来站点甚至可以为常见情况共享标准化的错误 URI，以使通用客户端自动检测到它们。
title：错误的简短可读摘要。这是明确的指引，客户端必须使用 type 作为识别 API 错误类型的主要方式。
detail：较长的人类可读解释，带有完整的错误详细信息。
status：错误使用的 HTTP 状态代码。它必须与实际状态匹配，但可以包含在这里的 body 中以便参考。
instance：标识该特定故障实例的 URI 。它可以作为发生的这个错误的 ID，和/或到特定故障更多详细信息的链接，例如显示失败的信用卡交易细节的页面。

所有这些字段都是可选的（不过type是强烈建议使用的）。内容类型允许自由包含其他数据，只要它们不与这些字段冲突即可，因此你也可以在此处添加自己的错误元数据，并包含所需的其他任何数据。实例 URI 和类型 URI 都可以是绝对 URI，也可以是相对 URI 。
这里的思想是：

通过返回带有合适Content-Type标头的错误响应，API 能很容易地表明它们正在遵循这一标准。
这是一组简单的字段，可以轻松添加到大多数现有的错误响应顶部（如果还没有添加的话）。
客户端只需在请求中包含Accept: application/problem+json（和/或+xml）标头，即可轻松表明支持状态，从而在必要时进行迁移。
客户端逻辑可以轻松识别这些响应，并使用它们来显著改善通用和按 API 区分的 HTTP 错误处理操作。

怎样开始使用它呢？目前，这是一个提案的标准，因此它尚未普及，并且在理论上可能会发生变化。
不过它已经用在很多地方，包括 5G 标准之类中，并且有了适用于大多数语言和框架的一些便捷工具，包括：

ASP.NET的内置支持
Node.js 的通用库和Express库
JAVA 的通用库和Spring Web MVC库
Python 的通用库和Django REST API库
Ruby 的通用、Rails和Sinatra库
php 的通用库和Symfony库
Rust、Go、Scala、Haskell的库...

也就是说，它已经渗透到了大多数主流生态系统中站稳了脚跟，并且即将更进一步：让更多 API 和客户端开始使用，直到实现大规模的普及状态，即大多数 API 的错误格式都遵循其标准，使它成为所有场景的默认值，让我们大家都能从中受益。
我们该如何做到这一点呢？
如果你在构建或维护一个 API：

如果可以的话，请尝试使用适当的Content-Type响应标头以RFC 7807格式返回错误。
如果你有了一种错误格式，并且需要维护该格式以保证兼容性，请检查是否可以在格式顶部添加这些字段，并对其进行扩展以符合标准。
如果不能，请尝试检测传入的Accept标头中的支持，并在可能的情况下使用它来将原有的错误格式切换为标准格式。
使用你的 API?框架（比如这个框架）记录错误，表明它们将来会转向标准错误格式。

如果你在使用一个 API：

检查这些内容类型的错误响应，并用那里提供的数据改进你的错误报告和处理工作。
考虑在请求中包含带有这些内容类型的Accept标头，以表明支持状态并在可用时启用标准错误。
向你使用的 API 提出抱怨，希望它们以这种标准格式返回错误，就像抱怨那些不会费心返回正确状态代码的 API 一样。

至于大家：

参与其中！这是 IETF 新的“HTTP API 的构建块”工作组旗下的规范。你可以加入邮件列表以阅读并参与有关该规范和其他可行 API 标准规范规范的讨论，包括速率限制和API弃用等。
向你的同事和开发者朋友做宣传，并帮助大家简化错误处理的工作。

原文链接：
https://httptoolkit.tech/blog/http-api-problem-details/

【API 请求失败后发生了什么？】

推荐阅读

上一篇：碧螺春全部品牌,碧螺春怎么储存

下一篇：安吉白茶产地先容,安吉白茶网是安吉白茶原产地官方网站