Страницы, фильтры и поиск API

Параметры страницы есть не у каждого списка. Используйте только параметры конкретного метода из справочника.

Список объектов

GET /api/v1/objects принимает q, typeId, state, page, pageSize. По умолчанию page 1 и pageSize 25; верхняя граница pageSize 100.

GET /api/v1/objects?typeId=TYPE_ID&page=1&pageSize=25 HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY

Следующие страницы запрашивайте последовательно, сохраняя фильтр. Это живой список: при параллельном изменении данных он не является неизменным снимком для миграции.

Поиск

GET /api/v1/search принимает q, kinds, filter, page, pageSize. kinds — виды сущностей через запятую, filter — JSON допустимого поискового фильтра. Кодируйте query-параметры штатным URL encoder.

Начинайте с простого q=VPN. Поиск требует не менее двух букв или цифр. Фильтр применяется к разрешённой поисковой проекции, а не ко всем полям базы.

Как понять, есть ли ещё результаты

У ответа поиска свои поля: записи находятся в data.results, не в data.rows, как у списка объектов. Проверяйте hasMore: если он равен true, запросите следующую страницу с теми же условиями.

При totalExact: false значение total — только нижняя оценка числа найденных записей, а не полный итог. Поиск останавливает подсчёт после достаточного количества результатов для текущей страницы и проверки продолжения. Поэтому не используйте такой total или totalPages как окончательное число для отчёта. Значения facets также подсчитаны по результатам текущей страницы, не по всей базе.

При totalExact: true подсчёт завершён для этого запроса и доступных пользователю данных. Между запросами данные могут измениться — это всё ещё не зафиксированный снимок.

Условие содержит field, operator, value. Поддержаны equals, not-equals, contains, starts-with, in, is-empty, before, after, range. Для in передайте массив вариантов, для range — массив двух границ. Для сложного фильтра используйте группу:

{
  "logic": "AND",
  "conditions": [
    {"field": "kind", "operator": "equals", "value": "object"}
  ]
}

Это JSON-значение параметра filter, передаваемое после URL-кодирования. Доступны группы AND/OR, до 20 условий в группе и ограниченная глубина вложенности. Не переносите произвольное выражение из UI, SQL или другой системы в filter.

Чего не обещает контракт

У objects нет общего параметра sort. Параметры page/pageSize не применяются автоматически к комментариям, identity, webhook или статьям. Публичный маршрут поиска не принимает cursor как универсальный параметр. Для передачи данных используйте импорт/экспорт, учитывая их ограничения.

Связанные статьи

• Справочник объектов
• Схемы типов
• Ошибки