Остальное API окутывает или нет

Question

У меня есть один вопрос, который мне трудно четко определить правильный ответ.

Мой API имеет одну конечную точку, которая выполняет разбиение на страницы. Итак, в ответе я должен вернуть клиенту общее количество строк, затронутых запросом. Количество записей на практике.

Я читал, что я должен передавать метаданные, как то, что я хочу, в теле, обволакивая его, но я также читал, что нехорошо модифицировать тело метаданными и что будущее должно вернуться только не метаданные о теле, что означает, что оно должно быть в заголовке ответа.

O'reilly 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"
  }
}

A аналогичный подход описан в RFC 5005 : каждая страницаРезультаты - это отдельный ресурс, который содержит гиперссылки на предыдущую и следующую страницу результатов

---

Вы также можете использовать заголовок 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"

Проверьте отношения ссылок , зарегистрированные в IANA .

---

Для возврата количества записей я видел некоторые API, использующие пользовательские заголовки, такие каккак X-Total-Count, но я не рекомендую такой подход.Затем отправьте эти данные в ответную полезную нагрузку.