Rest API 封装与否

Question

我有一个问题，我很难清楚地确定正确答案。

我的 API 有一个执行分页的端点。因此，在响应中，我必须向客户端返回受查询影响的总行数。实际记录数。

我已经读过，我应该像我想要的那样在正文中传递元数据，包裹它，但我也读过，用元数据影响正文是不行的，未来是回归主体上只有非元数据，这意味着它必须在响应头上。

奥莱利 If the information you are conveying through a custom HTTP header is important for the correct interpretation of the request or response, include that information in the body of the request or response or the URI used for the request. Avoid custom headers for such usages.

那么，我的问题是，解决问题的正确方法是什么？我应该在响应标头中传递行数还是将其放入消息正文中。

非常感谢。

Answer 1

对于分页，您可以在响应负载中使用信封：

{
  "data": [...],
  "paging": {
    "first": "http://api.example.com/foo?page=1&size=10",
    "previous": "http://api.example.com/foo?page=2&size=10"
    "next": "http://api.example.com/foo?page=4&size=10"
    "last": "http://api.example.com/foo?page=5&size=10"
  }
}

RFC 5005 中描述了similar approach：每页结果都是一个单独的资源，其中包含指向上一页和下一页结果的超链接

---

您也可以使用Link 标头（换行符只是为了便于阅读）：

Link: <http://api.example.com/foo?page=1&size=10>; rel="first", 
      <http://api.example.com/foo?page=2&size=10>; rel="previous",
      <http://api.example.com/foo?page=4&size=10>; rel="next", 
      <http://api.example.com/foo?page=5&size=10>; rel="last"

检查link relations registered in IANA。

---

对于返回记录数，我见过一些使用自定义标头的 API，例如 X-Total-Count，但我不推荐这种方法。然后在响应负载中发送这些详细信息。