在 RESTful Web 服务中设计分页端点的最佳方式

Posted 2023-02-19

【中文标题】在 RESTful Web 服务中设计分页端点的最佳方式

【英文标题】：Best way for designing a pagination endpoint in a RESTful Web Service

【发布时间】：2015-01-19 02:57:33

【问题描述】：

我的 RESTful Web 服务上有我的 /entities 端点，如果使用 GET 请求调用，它会返回所有数据库中存储的实体。

我现在想创建的是分页功能。仅检索这些结果的一页而不是所有实体的能力，只是为了最小化响应的大小。

我正在考虑两种方法。

通过/entities 端点上的查询参数 以GET 请求发送分页信息。例如，/entities?page=1&size=10

使用另一个HTTP Method，例如OPTIONS（我知道它不是为这种事情而设计的）。我不处理我的 Web 服务上的 OPTIONS 请求，我可以利用这一点，同时保持 RESTful Web 服务的本质，即对不同的操作使用不同的 HTTP Methods。在这种情况下，端点可能是这样的：/entities/1/10，（我认为）它更用户友好。

这两种选择都可以实现，我想事先知道哪一种更符合 REST 设计标准。

【问题讨论】：

Pagination in a REST web application 的可能重复项

【参考方案1】：

基于 HATEOAS（超媒体作为应用程序状态引擎）标准，响应应该与上一页和下一页链接。

/entities?page=1&size=10 优于 /entities/1/10，因为（严格来说）1/10 不是通过 URI 定位的资源。

【参考方案2】：

正如 aljo f 所说，没有官方标准。但在寻找最佳实践时，我发现了这个网站：

http://www.restapitutorial.com

在资源页面中有一个下载 .pdf 的链接，其中包含作者建议的完整 REST 最佳实践。其中有一个关于分页的部分。

作者建议添加对使用 Range 标头和使用查询字符串参数的支持。

请求

HTTP 头示例：

Range: items=0-24

查询字符串参数示例：

GET http://api.example.com/resources?offset=0&limit=25

其中 offset 是开始项目编号，limit 是要返回的最大项目数。

回应

响应应包含一个 Content-Range 标头，指示正在返回的项目数以及尚待检索的总项目数

HTTP 标头示例：

Content-Range: items 0-24/66

Content-Range: items 40-65/*

在 .pdf 中还有一些针对更具体案例的其他建议。

【参考方案3】：

我相信 RESTful Web 服务没有官方的“标准”。但是不同的供应商有很多建议/实施。

您的第一种方式是使用查询参数是正确的方式。不同的 HTTP 方法（GET、PUT、DELETE、POST）用于不同类型的操作。我从未听说过它们被用于修改现有操作。

请看Wikipedia - REST