Пагинация запросов Web API

Некоторые методы возвращают множество объектов (диалоги, пользователи, события и т.д.). Мы предоставляем удобный способ получить весь набор данных за несколько последовательных запросов. Используется cursor-based пагинация.

В зависимости от запроса, ключом пагинации может выступать разные параметры данных:

Значение первичного ключа
Поле с датой (в виде timestamp)
Пара из поля с датой и timetstamp.

Пагинация версии 2 (актуальная)

Применяется, если вы используете API без версии или с версией больше 2 (включительно).
Подробнее про версионирование.

Параметры пагинации v2 (query-параметры `GET` методов):

paginate_position - JSON-массив элементов. Содержит текущую позицию курсора пагинации. Содержимое массива может отличаться в зависимости от запроса. Наиболее распространены:
- Пагинация по первичному ключу. Тогда массив содержит одно целое число - id элемента. Id может быть задан строкой или числом (см. id_as_string).
- Пагинация по дате. Тогда массив содержит в первом элементе timestamp, во втором - id элемента. id элемента нужен, чтобы корректно пагинировать данные если timestamp большого числа элементов совпадает.
Для некоторых запросов доступны не все направления пагинации. Об этом будет написано в описании конкретного запроса.
paginate_count - Целое число от 1 до 50. Количество записей для выборки. Если указан paginate_position=around, то с каждой стороны получится до paginate_position / 2 элементов. По умолчанию: 20.
paginate_direction - [after, before, around]. Направление пагинации относительно paginate_position:
- after означает, что пагинация вернет значения с ключом большим, чем paginate_position.
- before (по умолчанию) означает, что пагинация вернет значения с ключом меньшим, чем paginate_position.
- around попытается выбрать заданное количество элементов вокруг paginate_position.
paginate_including - [true | false]. Включать ли элемент, указанный в paginate_position. По умолчанию false.
paginate_page_order - [asc, desc]. Порядок сортировки получившейся страницы. По умолчанию desc.

Ответ запроса с пагинацией v2

Ответ запрос с пагинацией будет содержать в поле meta комбинацию из 2 полей:

next_before_position - при пагинации before и around указывает следующую позицию курсора paginate_position c paginate_direction=before
next_after_position - при пагинации after и around указывает следующую позицию курсора paginate_position c paginate_direction=after

Если какое-то из полей содержит null, значит больше страниц для пагинации в данном направлении нет.

Пример:

GET https://api.carrotquest.io/apps/{ID}/conversations
По умолчанию используется paginate_position=before.

{
  "meta": {
    "next_before_position": [
      1684739969.358085,
      1160406004324630614
    ],
    "status": 200
  },
  "data": [
    ... // Objects here
  ]
}

Следующий запрос будет выглядеть так:
GET https://api.carrotquest.io/apps/{ID}/conversations?paginate_position=[1684739969.358085, 1160406004324630614]

Пагинация версии 1 (устаревшая)

Применяется, если вы используете API с мажорной версией 1.
Подробнее про версионирование.

Note Для обратной совместимости параметр называется after, хотя фактически он соответствует paginate_position=before в версии 2.

Важно! В 1 версии пагинации по дате есть логическая ошибка, в результате которой при одинаковых timestamp у большого числа записей часть данных может быть пропущена. Это очень редкая, но возможная ситуация.

Параметры пагинации v1 (query-параметры `GET` методов):

after - Содержит текущую позицию курсора пагинации. Значением является ID, timestamp или null (см. типы данных). Как и в случае с пагинацией версии 2, это число может интерпретироваться по-разному (timestamp, первичный ключ и др.)
count - задает максимальное количество объектов, которые будут возвращены в вызове (от 1 до 50). По умолчанию: 20.
including - [true | false]. включать ли элемент, указанный в after
page_order - [asc, desc]. Порядок сортировки получившейся страницы.

Ответ запроса с пагинацией v1

Ответ запрос с пагинацией будет содержать в поле meta поле next_after:

значение курсора пагинации, если есть следующая страница
null, если следующей страницы нет.

Пример:

GET https://api.carrotquest.io/apps/{ID}/conversations

{
  "meta": {
    "next_after": 1684740107.380634,
    "status": 200
  },
  "data": [
    ... // Objects here
  ]
}

Следующий запрос будет выглядеть так:
GET https://api.carrotquest.io/apps/{ID}/conversations?after=1684740107.380634