来自RESTful API的分页响应有效负载 [英] Pagination response payload from a RESTful API

问题描述

我想在我的RESTful API中支持分页.

I want to support pagination in my RESTful API.

我的API方法应通过/products/index返回产品的JSON列表.但是，可能有成千上万种产品，我想对它们进行分页，因此我的请求应如下所示:

My API method should return a JSON list of product via /products/index. However, there are potentially thousands of products, and I want to page through them, so my request should look something like this:

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

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

But what does my JSON response need to look like? Would API consumers typically expect pagination meta data in the response? Or is only an array of products necessary? Why?

Twitter的API似乎包含元数据: https://dev .twitter.com/docs/api/1/get/lists/members (请参见示例请求).

It looks like Twitter's API includes meta data: https://dev.twitter.com/docs/api/1/get/lists/members (see Example Request).

具有元数据:

{
  "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"
    }
  ]
}

只是一组产品(没有元数据):

Just an array of products (no meta data):

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

推荐答案

ReSTful API主要由其他系统使用，这就是为什么我将分页数据放在响应标头中的原因.但是，某些API使用者可能无法直接访问响应标头，或者可能正在您的API上构建UX，因此提供一种(按需)检索JSON响应中的元数据的方法是一个加号.

ReSTful APIs are consumed primarily by other systems, which is why I put paging data in the response headers. However, some API consumers may not have direct access to the response headers, or may be building a UX over your API, so providing a way to retrieve (on demand) the metadata in the JSON response is a plus.

我认为您的实现应默认包含机器可读的元数据，并且在请求时应包括人类可读的元数据.如果您愿意或最好通过查询参数(例如include=metadata或include_metadata=true)按需发送，则人类可读的元数据可以随每个请求一起返回.

I believe your implementation should include machine-readable metadata as a default, and human-readable metadata when requested. The human-readable metadata could be returned with every request if you like or, preferably, on-demand via a query parameter, such as include=metadata or include_metadata=true.

在您的特定情况下，我将在记录中包括每个产品的URI.这使API使用者可以轻松地创建指向各个产品的链接.我还将根据我的分页请求的限制设置一些合理的期望.可接受并记录页面大小的默认设置.例如， GitHub的API 将默认页面大小设置为30条记录，最多100条记录，再加上对查询API的次数设置速率限制.如果您的API具有默认的页面大小，则查询字符串仅可以指定页面索引.

In your particular scenario, I would include the URI for each product with the record. This makes it easy for the API consumer to create links to the individual products. I would also set some reasonable expectations as per the limits of my paging requests. Implementing and documenting default settings for page size is an acceptable practice. For example, GitHub's API sets the default page size to 30 records with a maximum of 100, plus sets a rate limit on the number of times you can query the API. If your API has a default page size, then the query string can just specify the page index.

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

In the human-readable scenario, when navigating to /products?page=5&per_page=20&include=metadata, the response could be:

{
  "_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"
    }
  ]
}

对于机器可读的元数据，我会在响应中添加链接标头 :

For machine-readable metadata, I would add Link headers to the response:

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响应标头，如果您选择的话:

...and possibly a custom total-count response header, if you so choose:

total-count: 521

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

The other paging data revealed in the human-centric metadata might be superfluous for machine-centric metadata, as the link headers let me know which page I am on and the number per page, and I can quickly retrieve the number of records in the array. Therefore, I would probably only create a header for the total count. You can always change your mind later and add more metadata.

顺便说一句，您可能会注意到我从您的URI中删除了/index.一个普遍接受的约定是让您的ReST端点公开集合.结束时加上/index会使它稍微增加.

As an aside, you may notice I removed /index from your URI. A generally accepted convention is to have your ReST endpoint expose collections. Having /index at the end muddies that up slightly.

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

These are just a few things I like to have when consuming/creating an API. Hope that helps!

这篇关于来自RESTful API的分页响应有效负载的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！