API设计

参考

首先，我想引用这篇文章中的所有内容。请阅读原文了解所有细节。如果我们合作的话，我会重点强调三点。

实体

几乎所有路由都应该代表一个实体或实体集合。这意味着需要分页和适当的筛选功能供客户端使用。如果客户端请求更新某个实体，则该实体应该包含在响应中。上面的参考资料对此主题进行了详细阐述。

散装作业

上述文章并未涵盖批量操作。我的建议如下：

POST /route
...headers

[{ids: [1, 3], status: 0}, {ids: [2], status: 1}]

这样应该会返回修改后的实体，以便客户端可以将数据合并到其状态中。

错误

最后我想强调的是错误处理。客户端问题使用 4xx HTTP 状态码，服务器端问题使用 5xx HTTP 状态码。大多数 JavaScript 客户端库会自动将 4xx 和 5xx HTTP 状态码解析为错误。因此，我认为使用正确的 HTTP 状态码并非硬性要求。响应签名应为：

{
  "message" : "Something bad happened :(",
  "description" : "More details about the error here"
}

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

大多数情况下，客户端应该能够直接在界面中输入消息字段。这意味着消息内容应该易于最终用户阅读和理解，并且长度应少于 200 个字符。

额外的

• JSON 键中不应包含空格。
• 如果请求发送了Accept: application/json标头，后端也应该做出相应的响应。

太好了！现在我们可以一起工作了！