我想支持分页在我的RESTful API。
我的API方法应通过返回产品的JSON列表/products/index 。 不过，也有潜在的成千上万的产品，我想通过他们的页面，所以我的要求应该是这个样子：
/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"
}
]
RESTful API中主要是由其他系统，这就是为什么我把传呼数据的响应头消耗。 然而，一些API的消费者可以不必响应报头的直接访问，也可以建立在你的API一个UX，所以提供了一个方法来检索（需求）的JSON响应中的元数据被加分。
我相信，在请求时实现应包括机器可读的元数据为默认值，和人类可读的元数据。 人类可读的元数据可以与每个请求，如果你喜欢或返回，优选，按需经由查询参数，如include=metadata或include_metadata=true 。
在您的特定情况下，我将包括URI与记录每一个产品。 这很容易让该API消费者创造链接到各个产品。 我还要设置一些合理的期望按我的寻呼请求的限制。 实施和页面大小文档的默认设置是一个可以接受的做法。 例如， GitHub的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: </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
在人类为中心的元数据所揭示的其它寻呼数据可能是多余的机器为中心的元数据，链接标题让我知道哪一页我就和每个页面的数量，我可以快速检索数组中的记录数。 因此，我可能只会创造了总数的标题。 以后您可以随时改变主意，并添加更多的元数据。
顺便说一句，你可能会注意到我删除/index从URI。 普遍接受的传统是让你休息端点暴露集合。 有/index在年底muddies是略有上升。
这些都只是几件事情，我喜欢消费时有/创建API。 希望帮助！
至于谁写几个库使用REST服务的人，让我给你的，为什么我觉得包装的结果元数据是要走的路该客户端的角度：
- 如果没有总数，客户端怎么能知道它尚未收到一切有，应通过结果继续分页设置？ 在未进行展望下一个页面，在此可表示为一个Next /更多的链接，实际上并没有取得任何更多的数据最坏的情况下的UI。
- 在响应中包括元数据允许客户端跟踪少的状态。 现在，我不必匹配与响应我的REST请求，作为响应包含重建请求状态（在这种情况下，光标移动到数据集）所需的元数据。
- 如果状态是响应的一部分，我可以同时执行多个请求到同一数据集，我可以处理任何顺序，他们碰巧在到达的请求不一定我提出的要求的顺序。
并建议：像Twitter的API ，你应该用直线指数/鼠标更换PAGE_NUMBER。 原因是，该API允许客户端设置每个请求的页面大小。 是返回PAGE_NUMBER页的客户端请求，到目前为止，或者是给定最后使用PAGE_SIZE页面数数（几乎可以肯定是过去了，但是为什么不能完全避免这样的歧义）？
我会建议增加对相同的头文件。 移动元数据报头在摆脱类似信封的帮助result ， data或records和响应主体只包含我们需要的数据。 您可以使用连接头，如果你生成分页链接了。
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
对于招摇文件：
https://github.com/adnan-kamili/swagger-response-template
