4. Defining New Problem Types (定义新的问题类型)
当 HTTP API 需要定义指示错误条件的响应时, 通过定义新的问题类型来这样做可能是合适的。
在这样做之前, 重要的是要了解它们擅长什么以及什么最好留给其他机制。
问题详情不是底层实现的调试工具; 相反, 它们是一种暴露有关 HTTP 接口本身更多详情的方式。新问题类型的设计者需要仔细考虑安全考虑 (第 5 节), 特别是通过错误消息暴露实现内部信息而暴露攻击向量的风险。
同样, 真正通用的问题 -- 即可能适用于 Web 上任何资源的条件 -- 通常最好表示为普通状态码。例如, "write access disallowed" 问题可能是不必要的, 因为对 PUT 请求的 403 Forbidden 状态码响应是不言自明的。
最后, 应用程序可能有更合适的方式以其已定义的格式承载错误。问题详情旨在避免建立新的"故障"或"错误"文档格式的必要性, 而不是替换现有的特定于域的格式。
话虽如此, 可以使用 HTTP 内容协商向现有 HTTP API 添加对问题详情的支持 (例如, 使用 Accept 请求头来指示对此格式的偏好; 参见 [HTTP] 的第 12.5.1 节)。
新的问题类型定义必须 (MUST) 记录:
-
一个 type URI (通常使用 "http" 或 "https" 方案)
-
一个适当描述它的 title (简短)
-
与之一起使用的 HTTP 状态码
问题类型定义可以 (MAY) 在适当情况下指定使用 Retry-After 响应头 ([HTTP] 的第 10.2.3 节)。
问题类型 URI 应该 (SHOULD) 解析为 HTML [HTML5] 文档, 该文档解释如何解决问题。
问题类型定义可以 (MAY) 在问题详情对象上指定附加成员。例如, 扩展可能使用类型化链接 [WEB-LINKING] 到机器可以用来解决问题的另一个资源。
如果定义了此类附加成员, 其名称应该 (SHOULD) 以字母开头 (ALPHA, 如 [ABNF] 附录 B.1 所述), 并应该 (SHOULD) 包含来自 ALPHA、DIGIT ([ABNF] 附录 B.1) 和 "_" 的字符 (以便可以在 JSON 以外的格式中序列化), 并且它们应该 (SHOULD) 为三个字符或更长。
4.1. Example (示例)
例如, 如果您正在为在线购物车发布 HTTP API, 您可能需要指示用户信用额度不足 (我们上面的示例), 因此无法进行购买。
如果您已经有一个可以容纳此信息的特定于应用程序的格式, 那可能是最好的做法。但是, 如果没有, 您可能会使用问题详情格式之一 -- 如果您的 API 基于 JSON, 则使用 JSON, 或者如果使用该格式, 则使用 XML。
为此, 您可能会在注册表 (第 4.2 节) 中查找已定义的适合您目的的 type URI。如果有可用的, 您可以重用该 URI。
如果没有可用的, 您可以创造并记录一个新的 type URI (应该在您的控制之下并且随时间稳定)、一个适当的 title 和将与之一起使用的 HTTP 状态码, 以及它的含义和应该如何处理。
4.2. Registered Problem Types (已注册的问题类型)
本规范定义了"HTTP Problem Types"注册表, 用于常见的、广泛使用的问题类型 URI, 以促进重用。
此注册表的策略是 Specification Required, 根据 [RFC8126] 第 4.6 节。
在评估请求时, 指定的专家应考虑社区反馈、问题类型的定义程度以及本规范的要求。特定于供应商、特定于应用程序和特定于部署的值无法注册。规范文档应以稳定、免费可用的方式发布 (理想情况下使用 URL 定位), 但不需要是标准。
注册可以 (MAY) 对 type URI 使用前缀 "https://iana.org/assignments/http-problem-types#"。请注意, 这些 URI 可能无法解析。
以下模板应用于注册请求:
Type URI: [问题类型的 URI]
Title: [问题类型的简短描述]
Recommended HTTP status code: [最适合与该类型一起使用的状态码]
Reference: [定义该类型的规范]
有关发送注册请求的详细信息, 请参见 https://iana.org/assignments/http-problem-types 上的注册表。
4.2.1. about:blank
本规范注册一个问题类型 "about:blank", 如下所示。
Type URI: about:blank
Title: See HTTP Status Code
Recommended HTTP status code: N/A
Reference: RFC 9457
"about:blank" URI [ABOUT] 用作问题类型时, 表示该问题除了 HTTP 状态码之外没有其他语义。
当使用 "about:blank" 时, title 应该 (SHOULD) 与该代码的推荐 HTTP 状态短语相同 (例如, 404 为 "Not Found" 等), 尽管它可以 (MAY) 本地化以适应客户端偏好 (使用 Accept-Language 请求头表示)。
请注意, 根据 "type" 成员的定义方式 (第 3.1 节), "about:blank" URI 是该成员的默认值。因此, 任何不携带显式 "type" 成员的问题详情对象都隐式使用此 URI。