rest - 来自 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

ReSTful API 主要由其他系统使用，这就是我将分页数据放入响应 header 中的原因。但是，某些 API 使用者可能无法直接访问响应 header ，或者可能正在通过 API 构建 UX，因此提供一种在 JSON 响应中检索(按需)元数据的方法是一个优势。

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

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

在人类可读的场景中，当导航到 /products?page=5&per_page=20&include=metadata 时，响应可能是:

{
  "_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 headers回复:

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

(链接 header 值应进行 urlencoded)

...以及可能的自定义total-count响应 header ，如果您选择的话:

total-count: 521

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

顺便说一句，您可能会注意到我从您的 URI 中删除了 /index。普遍接受的约定是让您的 ReST 端点公开集合。最后加上 /index 会使情况稍微变得困惑。

这些只是我在使用/创建 API 时喜欢的一些东西。