时间戳

首页 > 解决方案 > API 设计 - 客户端请求中的可选正文 - 验证失败时返回的状态码

rest - API 设计 - 客户端请求中的可选正文 - 验证失败时返回的状态码

问题描述

在我们的 API 中，其中一个端点将期望客户端仅在某些情况下提供正文/有效负载。

如果 API 无法根据客户端的来源为给定请求生成有效负载，那么我们希望我们的 API 向客户端提供带有正确状态代码的响应，以便他们知道他们必须提供额外的信息。一旦客户端使用 body/payload 完成请求，那么 api 将照常处理请求。

我只是想知道在 API 设计中是否有任何标准的、预定义的状态代码或程序来实现这种端点，或者我们是否必须使用一些自定义状态代码拒绝请求，然后要求客户端实现基于自定义的逻辑代码？。

谢谢，

维诺特

标签： restapi-designhttp-status-codesendpointstatus

解决方案

HTTP 状态代码不会也不打算精确映射到每个现实世界的错误。它们代表错误的类别。

例如，404 表示找不到资源，但如果您的路径是 /customers/11/animals/5，那么路径可能有几处错误。例如，客户 11 可能没有动物 5，或者可能没有客户 11。“未找到动物”没有 http 响应。或者您的 API 可能没有任何使用该 URL 模式开始的调用。

您应该返回一个状态代码，它代表您遇到的错误的“类别”（在这种情况下，没有找到某些东西），并且响应正文应该包含有关错误的更具体的详细信息。为了使事情更简单，我发现如果数据结构对于成功和错误（它使解析更容易）相同，并且“数据”字段因响应而异，这将很有帮助。

这是一个例子：

status code: 404 not found
body: { 
    "messageDetailCode" :"CustomerNotFound", 
    "messageDetail" : "Customer not found", 
    "data" : null 
}

进一步阅读：

REST API 服务针对验证失败返回什么适当的 HTTP 状态代码？

推荐阅读