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

Posted 2023-02-19

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

【英文标题】：API design - Optional body in client request - Status code to return if validation fails

【发布时间】：2020-10-05 16:25:38

【问题描述】：

在我们的 API 中，其中一个端点会期望客户端仅在特定场景中提供正文/有效负载。

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

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

谢谢，

维诺特

【参考方案1】：

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 

进一步阅读：

What's an appropriate HTTP status code to return by a REST API service for a validation failure?