为什么要在 API 响应中提供分页信息？答案

【问题标题】：Why providing pagination information in API response?为什么要在 API 响应中提供分页信息？
【发布时间】：2013-06-25 02:24:45
【问题描述】：

我们现在正在设计我们的 RESTful API，我有一个关于如何公开分页信息的问题。

似乎一些著名的服务，如 Github 或 Firefox Market Place 在其 API 中具有如下内容：

{
"meta": {
    "limit": 3,
    "next": "/api/v1/apps/category/?limit=3&offset=6",
    "offset": 3,
    "previous": "/api/v1/apps/category/?limit=3&offset=0",
    "total_count": 16
    }
}

我的问题是：

为什么服务器要在响应中给出完整的下一个/上一个 url？

在我看来，客户正在发出第一个请求。所以它知道它曾经调用过哪些参数（偏移量/限制/api版本）。客户端很容易弄清楚下一个/上一个要调用的 url 是什么。为什么要费心计算多余的 url 并将其提供给客户端？

【问题讨论】：

使用分页可以保护您免受用户通过大型查询占用您的所有资源。例如，将返回项目的数量限制为 20。您可以传递页面，以方便用户。
@Matt 我认为您错过了 OP 提出的确切问题。这是“当客户端清楚地知道如何生成它们时，为什么要在响应中提供 URL？”而不是“为什么要使用分页？”
@MattBall 感谢您为我澄清。你说的正是我要输入的内容。

标签： api restful-url api-design

【解决方案1】：

我是RESTful！这是HATEOAS, or Hypermedia as the Engine of Application State.

的一部分

除了应用程序的简单固定入口点之外，客户端不假定任何特定资源可用于任何特定资源，而不是先前从服务器接收到的表示中描述的那些。

和：

[HATEOAS] 是 REST 应用程序架构的一个约束，将它与大多数其他网络应用程序架构区别开来。其原理是客户端完全通过应用服务器动态提供的超媒体与网络应用进行交互。 REST 客户端不需要事先了解如何与任何特定应用程序或服务器交互，而无需对超媒体有一般的了解。
...
REST 客户端通过简单的固定 URL 进入 REST 应用程序。 客户端可能采取的所有未来操作都在从服务器返回的资源表示中发现。

（已添加重点）

在我看来，客户正在发出第一个请求。所以它知道它曾经调用过哪些参数（offset/limit/api 版本）。

是的，客户端发出第一个请求，但这并不意味着它知道有关 URL 发现、分页、限制/偏移参数等的任何信息。

【讨论】：

感谢您的回答，马特。我仍然不确定为什么“这并不意味着它对 URL 发现、分页、限制/偏移参数等一无所知”。由于客户端启动请求，它知道它正在请求哪个页面（偏移量），一个页面上有多少项目（限制）以及它正在调用的 api 版本。即使客户端在请求后不会持久化这些信息，服务器也可以在响应中回显“偏移”、“限制”而不是完整的 uri。
我猜为什么会在响应中给出完整的 uri，可能 API 设计者是 Atom 协议的粉丝，所以以 RFC5005|ietf.org/rfc/rfc5005.txt 为起点。但 RFC5005 不同：它在服务器响应中包含 first/next/pre/last 全部，因此分页对客户端绝对透明。
“由于客户端开始请求，它知道它正在请求哪个页面（偏移量），一个页面上有多少项目（限制）”不，那不是真的.我的回答中的第一句话直接反驳了这一点。客户端在请求事物列表时不一定知道它正在接收分页响应。