REST API错误代码返回结构

Question

我正在编写一个REST API,我偶然发现了一个问题.返回验证错误的最佳方法是什么.

到目前为止,我已经将转储的错误消息返回到一般错误代码中(例如,假设请求错误)

{
    "status": 400,
    "error": {
        "code": 1, // General bad request code
        "message": [
                "The Key \"a\" is missing",
                "The Key \"b\" is missing",
                "The Key \"c\" is missing",
                "Incorrect Format for field \"y\""
         ]
    }

)

我已经研究了一些关于良好的API响应应该是什么样子的更多信息,我想到了以下几个选项:

1. 停止第一次遇到的错误并返回带有特定错误代码的响应

   {
      "status": 400, //Same as the HTTP header returned
      "error" {
           "code": 1, // Specific field validation error code
           "message": "Field \"x\" is missing from the array structure",
           "developer_message": "The request structure must contain the following fields {a,b,c{x,y,z}}",
           "more_info" => "www.api.com/help/errors/1"
       }
   )
   

2. 解析所有请求数据并返回多个字段验证错误.

   {
     "status": 400,
     "error": {
       "code": 1 //General bad Request code
       "message": "Bad Request",
       "developer_message": "Field validation errors."
       "more_info": "www.api.com/help/errors/1",
       "error_details": {
               0: {
                       "code": 2 // Specific field validation error code
                       "message": "Field \"x\" is missing from the array structure",
                       "developer_message": "The request structure must contain the following fields {a,b,c{x,y,z}}",
                       "more_info": "www.api.com/help/errors/2"
                   },
   
               1: {
                       "code": 3 // Specific field validation error code
                       "message": "Incorrect Format for field \"y\"",
                       "developer_message": "The field \"y\" must be in the form of \"Y-m-d\"",
                       "more_info": "www.api.com/help/errors/3"
                  }
                      }
         }
     }
   

在我看来,选项2将是正确的方式(它为开发人员/最终用户提供更多有用的信息,服务器负载可能更低(更少的请求/不需要重新验证有效数据/不需要计算签名和验证用户)),但我在徘徊什么是最佳实践,如果还有另一种方法来处理这类问题.

此外,我认为如果我在脚本流中遇到单个致命错误,则选项1仍然有效.(不是验证错误)

请注意,代码只是一个简单的数组,因此更容易理解.响应格式为JSON或XML.

Answer 1

我们来看看Facebook的Graph API.这很难受,很有可能产生很多错误.这是Facebook在API错误上返回的内容:

 {
   "error": {
     "message": "Message describing the error", 
     "type": "OAuthException", 
     "code": 190,
     "error_subcode": 460,
     "error_user_title": "A title",
     "error_user_msg": "A message"
   }
 }

他们尝试使Graph API尽可能有用,但它们似乎返回了代码和子代码(Ref)的特定错误.每个错误都有自己的代码这一事实意味着更容易搜索所述代码或消息作为调试的起点.这可能就是为什么他们不会在官方错误响应中累积错误消息.如果它对Facebook来说足够好又方便,那对我们来说可能已经足够了.

示例错误响应:

{
  "error": {
    "message": "(#200) Must have a valid access_token to access this endpoint", 
    "type": "OAuthException", 
    "code": 200
  }
}

和

"error": {
  "message": "(#604) Your statement is not indexable. The WHERE clause must contain 
   an indexable column. Such columns are marked with * in the tables linked from
   http://developers.facebook.com/docs/reference/fql ", 
  "type": "OAuthException", 
  "code": 604
}

然后是JSend,"这是一个规范,规定了如何格式化来自Web服务器的JSON响应的规则." 他们的目标是:

有很多Web服务提供JSON数据,每个都有自己的格式化响应方式.此外,为JavaScript前端编写的开发人员不断重新发明从服务器传输数据的方法.虽然有许多用于构造此数据的常见模式,但在命名或响应类型等方面没有一致性.此外,这有助于促进后端开发人员和前端设计人员之间的幸福和团结,因为每个人都可以期望一种共同的方法来相互交流.

这是一个示例错误消息:

{
    "status" : "fail",
    "data" : { "title" : "A title is required" }
}

看起来Facebook和这个试图像行业标准设定的群体选择了你的选择#1.

赏金问题

为了响应"如果有人去了#2并且可能对它有任何改进？"的赏金请求,Pragmatic RESTful API有一种设计模式,它表明:

验证错误需要现场细分.最好通过使用固定的顶级错误代码进行验证失败并在其他错误字段中提供详细错误来建模,如下所示:

{
  "code" : 1024,
  "message" : "Validation Failed",
  "errors" : [
    {
      "code" : 5432,
      "field" : "first_name",
      "message" : "First name cannot have fancy characters"
    },
    {
       "code" : 5622,
       "field" : "password",
       "message" : "Password cannot be blank"
    }
  ]
}

Answer 2

就我个人而言，我会给用户提供较少的细节，并将开发人员所需的错误转储到数据库日志表或系统日志中。由于您使用的是 JSON，这在 Apache 服务器上最常见，并且您的代码看起来可能是 php（但带有大括号的代码示例可能是源自 PASCAL 的多种语言，例如 C、C# PERL、PHP、 CSharp）。如果您还不知道 php http://php.net/manual/en/function.syslog.php中的操作方法，则以下是如何将输出自定义错误添加到系统日志中。如果您使用的是带有 JSON 和 CSharp 的罕见配置 IIS，也可以使用 .NET 库执行类似操作。如果您在发生错误时向用户提供了太多信息，那么您将来也会为黑客提供一种探测您网站的方法。