来自RESTful API的分页响应有效负载

Question

我想在RESTful API中支持分页。

我的API方法应该通过/Products/index返回产品的JSON列表。但是，可能有成千上万的产品，我想浏览它们，所以我的请求应该如下所示：

/products/index?page_number=5&page_size=20

但我的JSON响应需要是什么样的呢？API使用者通常会在响应中期望分页元数据吗？还是只需要一系列产品？为什么？

看起来Twitter的API包含元数据：https://dev.twitter.com/docs/api/1/get/lists/members（请参阅示例请求）。

使用元数据：

{
  "page_number": 5,
  "page_size": 20,
  "total_record_count": 521,
  "records": [
    {
      "id": 1,
      "name": "Widget #1"
    },
    {
      "id": 2,
      "name": "Widget #2"
    },
    {
      "id": 3,
      "name": "Widget #3"
    }
  ]
}

只是一个产品数组（没有元数据）：

[
  {
    "id": 1,
    "name": "Widget #1"
  },
  {
    "id": 2,
    "name": "Widget #2"
  },
  {
    "id": 3,
    "name": "Widget #3"
  }
]

Answer 1

作为一个为使用REST服务编写了多个库的人，让我从客户机的角度介绍一下为什么我认为将结果包装成元数据是一种可行的方法：

• 如果没有总数，客户机怎么知道它还没有收到所有的数据，应该继续在结果集中分页？在没有执行前瞻下一页的UI中，在最坏的情况下，这可能表示为下一个/多个链接，实际上没有获取更多数据

还有一个建议：像推特API一样，应该用直接的索引/光标替换page\u编号。原因是，API允许客户端设置每个请求的页面大小。返回的page\u number是客户端迄今为止请求的页数，还是给定上次使用的page\u大小的页数（几乎可以肯定是后者，但为什么不完全避免这种歧义）？

Answer 2

我建议添加相同的标头。将元数据移动到标头有助于摆脱信封，如结果、数据或记录和响应正文仅包含我们需要的数据。如果您也生成分页链接，则可以使用链接标头。

    HTTP/1.1 200
    Pagination-Count: 100
    Pagination-Page: 5
    Pagination-Limit: 20
    Content-Type: application/json

    [
      {
        "id": 10,
        "name": "shirt",
        "color": "red",
        "price": "$23"
      },
      {
        "id": 11,
        "name": "shirt",
        "color": "blue",
        "price": "$25"
      }
    ]

详情请参阅：

https://github.com/adnan-kamili/rest-api-response-format

对于swagger文件：

https://github.com/adnan-kamili/swagger-response-template

Answer 3

ReSTful API主要被其他系统使用，这就是为什么我将分页数据放在响应标头中。但是，一些API使用者可能无法直接访问响应标头，或者可能正在通过您的API构建用户体验，因此提供一种在JSON响应中检索（按需）元数据的方法是一个优势。

我相信您的实现应该默认包含机器可读元数据，并在请求时包含人类可读元数据。如果您愿意，可以在每次请求中返回人类可读元数据，或者最好通过查询参数按需返回，例如include=元数据或include_metadata=true。

在您的特定场景中，我将在记录中包含每个产品的URI。这使得API使用者可以轻松地创建指向各个产品的链接。我还将根据分页请求的限制设置一些合理的期望。实现和记录页面大小的默认设置是可以接受的做法。例如，GitHub的API将默认页面大小设置为30条记录，最大值为100条，并对您可以查询API的次数设置了速率限制。如果您的API具有默认页面大小，那么查询字符串只能指定页面索引。

在人类可读的场景中，当导航到产品时？页码=5

{
  "_metadata": 
  {
      "page": 5,
      "per_page": 20,
      "page_count": 20,
      "total_count": 521,
      "Links": [
        {"self": "/products?page=5&per_page=20"},
        {"first": "/products?page=0&per_page=20"},
        {"previous": "/products?page=4&per_page=20"},
        {"next": "/products?page=6&per_page=20"},
        {"last": "/products?page=26&per_page=20"},
      ]
  },
  "records": [
    {
      "id": 1,
      "name": "Widget #1",
      "uri": "/products/1"
    },
    {
      "id": 2,
      "name": "Widget #2",
      "uri": "/products/2"
    },
    {
      "id": 3,
      "name": "Widget #3",
      "uri": "/products/3"
    }
  ]
}

对于机器可读的元数据，我将向响应中添加链接头：

Link: </products?page=5&perPage=20>;rel=self,</products?page=0&perPage=20>;rel=first,</products?page=4&perPage=20>;rel=previous,</products?page=6&perPage=20>;rel=next,</products?page=26&perPage=20>;rel=last

（链接标头值应被urlencoded）

...以及可能的自定义Total-count响应标头，如果您选择：

total-count: 521

以人为中心的元数据中显示的其他分页数据对于以机器为中心的元数据可能是多余的，因为链接标头让我知道我在哪个页面以及每页的数量，并且我可以快速检索数组中的记录数量。因此，我可能只会为总计数创建一个标头。您可以稍后改变主意并添加更多元数据。

另外，您可能会注意到我从您的URI中删除了索引。普遍接受的约定是让ReSTendpoint公开集合。在末端有索引，使其略微变脏。

这些只是我在使用/创建API时喜欢的一些东西。希望有帮助！