在 Restful API 设计中应该返回空列表 [] 200/204 还是 404？

Question

例如，有一个restful APIGET http://luexu.com/users/{page}来列出第N 页中的用户。假设每个页面有 20 个用户。数据库中共有 100 个用户。GET http://luexu.com/users/5返回第 80 个到第 100 个用户。

那么查询GET http://luexu.com/users/10呢？它超出了总用户数。哪个是返回空列表、空数组[]或返回空数组的更好设计404？

200？

{
    "code": 200,
    "msg": "OK",
    "data": []
}

还是204？

{
    "code": 204,
    "msg": "OK",
    "data": []
}

还是404？

{
    "code": 404,
    "msg": "Not Found",
    "data": null
}

Answer 1

那么代码 204 怎么样？

在 HTTP 中，204 No Content意味着非常具体的东西——消息体的长度为零字节。

204（无内容）状态代码表示服务器已成功完成请求，并且响应负载正文中没有要发送的其他内容。

因此，如果您要发送例如 json 编码的文档，则不应该考虑它。

如果空列表是资源的可接受表示，那么200用作响应代码就可以了。例如，考虑堆栈溢出本身的 URI。

截至 2019-06-01，带有这些标签的问题少于 999 页，但服务器计算该页的正确表示没有问题（包括最高编号页为 426 的信息）。因此，的语义200非常合适。

404意味着没有可用的资源表示。所有4xx类响应代码都表示请求有错误——在这种情况下，它表明客户端对 URI 犯了错误。这可能是暂时的情况（您现在不应该询问该资源）。所以这也可以，如果你想表明客户端已经离开了域协议的快乐路径。

如何选择？我从HTTP 规范中的这个观察开始

服务器应该发送一个包含对错误情况的解释的表示，以及它是暂时的还是永久的情况。

那么哪个对客户有用呢？问题的表示，还是空集合的表示？当相同的资源用于不同的事情时，这可能是一个具有挑战性的问题。

Answer 2

这是没有“最佳”答案的问题之一。

您所能做的就是查看选项并选择最适合您的场景的选项。

根据经验，我个人会避免返回 404。原因是不清楚为什么会收到 404。您可能会收到 404，因为您的 URL 错误，因此如果您设计选择在没有 URL 的情况下返回 404数据，那么你最终会陷入一个不明确的境地。你怎么知道为什么会出现 404 错误？这可不行。

返回 200 和空数组是完全可以的。返回 204 也完全没问题。

重要的是做出选择，保持一致并记录选择，以便 API 的用户知道您做出了这个选择以及原因。

一致性和清晰性是我们的目标。