REST API 分页 - 如何处理超出总计数的偏移量

Question

我有一个 RESTful API，它使用 limit 和 offset 来处理分页（如 here 所述）。每个请求还返回可用项目的总数，以便客户端正确显示分页。

我想知道如何处理偏移量超过项目总数的调用。我可以轻松检测到这种情况，因为在获取任何记录之前会检查总计数 - 这允许我跳过记录获取调用作为微优化，因为我知道它不会返回任何内容。

我看到两个选项：

1. 一切照旧：我返回一个标准响应，但包含一个空的项目数组。
2. 404：未找到与此请求匹配的结果。这样做的好处是允许我发送一个空正文，但也有端点无效的歧义。

我不确定该选择哪个选项，或者是否有更好的选项。

编辑：似乎正确的解决方案是return a 204。它允许我发送一个空的正文，没有端点无效的歧义。

Answer 1

正如我在另一个答案中所说，我会使用以下之一：

• HTTP 200，count=0，返回列表中没有项目。
• HTTP 400，因为调用者要求的 url 无效
• HTTP 404，因为找不到要返回的项目

我认为在这种情况下返回错误（4xx + 错误信息）是安全的，因为以下假设之一可能会超出偏移量：

• 编码错误
• 调用程序未从一开始就获取数据（无新状态）
• Invoker 忽略了分页数据（出现在每个响应中）

由于有效负载，分页响应中的 HTTP 204 是不真实的。分页时，您应该返回分页信息，例如返回的项目、总项目、偏移量等，这在 HTTP 204 中是不允许的。