我应该在 restful api 中使用不同的状态代码，而不是仅使用 200 个吗？

Question

我正在开发 RESTful API 服务。我和我的团队负责人在以下主题上存在分歧："HTTP Response status codes"。

我的团队负责人说，用 RFC 编写的默认 HTTP 状态代码很糟糕，很难在客户端（前端）处理它们。他认为在响应主体中自定义状态代码，使用 HTTP 状态代码 200（每次 200）——最好的方法。当试图在没有权限的情况下执行操作时，他的响应正文将如下所示：

HTTP/1.1 200 OK

{
    code: 1005,  // Custom code instead 403
    data: {
        message: "Forbidden."
    }

}

我认为这是错误的回应方式。我的回复方案是这样的：

HTTP/1.1 403 Forbidden

{
    code: 403,
    success: false,
    message: "Forbidden."

}

我们应该使用 RFC HTTP 状态代码，还是可以使用我们自己的自定义代码？最好最正确的方法在哪里？

Answer 1

短片

你完全正确。

长答案

在 restful API 设计中，您必须使用 RFC-7231 中指定的官方 HTTP 代码。请不要为每个请求发送 200 OK。 200 OK 保留给实际成功的请求，并且服务器以特定资源的有效状态响应。大多数用例都有代码。如果您仍然需要区分相同类型的错误，例如 FORBIDDEN，您可以发送自定义错误代码。但是 HTTP 响应仍然是一个错误，因此您不能使用 200 OK。

关于您提出的错误方案，您不应在正文中发送代码和状态。这已经作为 HTTP 状态发送，因此是多余的。布尔成功标志也是多余的，因为 HTTP 代码的类型已经指出它是否成功（2xx => 成功，4xx 客户端错误，5xx 服务器错误）。正文应包含额外的上下文，这将有助于 API 客户解决问题。

精心设计的 API 错误响应应包含有助于解决可能问题的信息：

服务器上每个请求生成的请求 ID
详细的错误信息
（可选）内部错误代码
（可选）错误类别
（可选）参考 api documentation/error 描述

示例：

HTTP/1.1 403 Forbidden
{ 
    "requestId": "a5e5dd13-0047-4d2e-b96c-55a5031f0511", 
    "message": "You are not allowed to access this resource. Missing write permission.",
    "category": "AccessControl"
}

如果这仍然不足以让您的团队领导相信您可以指出一些设计良好的 REST API：

我应该在 restful api 中使用不同的状态代码，而不是仅使用 200 个吗？

Should I use different satus codes in restful api, instead only 200?

rest

http

rfc

短片

长答案