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

Каждый список API Notiondesk использует одну и ту же постраничную навигацию с помощью курсора, и каждый запрос может зафиксировать версию API, для которой была написана ваша интеграция, с помощью заголовка nd-version. В этой статье объясняется, как работает постраничная навигация API Notiondesk, как читать каждую страницу списка, как работает версионирование API и правила именования полей и параметров.

Как работает пагинация API Notiondesk

Все маршруты, указанные в списке, отвечают на один и тот же запрос:

{
  "object": "list",
  "data": [],
  "has_more": false,
  "next_cursor": null
}

Управляйте страницей с помощью двух параметров запроса:

В списках отсутствуют номера страниц и общее количество.

Прочитайте каждую страницу списка.

Повторяйте запрос, устанавливая значение cursor равным значению next_cursor из предыдущего ответа, пока значение has_more не станет равным false.

Первая страница:

На следующей странице NEXT_CURSOR заменено на закодированное в URL-формате next_cursor с первой страницы:

Тот же цикл в JavaScript:

А на языке Python:

Правила курсора

curl "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/articles?page_size=100" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16"

curl "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/articles?page_size=100&cursor=NEXT_CURSOR" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16"

async function listAll(path) {
  const items = [];
  let cursor = null;

  do {
    const url = new URL(`https://api.notiondesk.so${path}`);
    url.searchParams.set("page_size", "100");
    if (cursor) {
      url.searchParams.set("cursor", cursor);
    }

    const response = await fetch(url, {
      headers: {
        Authorization: `Bearer ${process.env.NOTIONDESK_API_KEY}`,
        "nd-version": "2026-10-16",
      },
    });
    const page = await response.json();

    items.push(...page.data);
    cursor = page.has_more ? page.next_cursor : null;
  } while (cursor);

  return items;
}

const articles = await listAll("/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/articles");

import os
import requests

def list_all(path):
    items, cursor = [], None
    while True:
        params = {"page_size": 100}
        if cursor:
            params["cursor"] = cursor
        page = requests.get(
            f"https://api.notiondesk.so{path}",
            params=params,
            headers={
                "Authorization": f"Bearer {os.environ['NOTIONDESK_API_KEY']}",
                "nd-version": "2026-10-16",
            },
        ).json()
        items.extend(page["data"])
        if not page["has_more"]:
            return items
        cursor = page["next_cursor"]

• Курсор непрозрачен. Не анализируйте его и не создавайте собственный курсор. Передайте его обратно в том виде, в котором вы его получили.

• Вы можете изменять page_size между страницами. Следующая страница начинается с того места, где закончилась предыдущая.

• Курсор фиксирует положение, а не моментальный снимок. Добавление или удаление элемента во время постраничного отображения может сместить последующие элементы, поэтому страница может повторять или пропускать один элемент. Если ваша интеграция удаляет элементы во время их отображения, начните заново с первой страницы.

• Некоторые списки обрываются раньше времени. Список изменений содержит максимум 1000 новых записей. Список перенаправлений страниц и отзывов содержит максимум 10 000 новых записей. После превышения этого лимита has_more превращается в false.

• Некоторые списки никогда не разбиваются на страницы. Темы оформления и интеграции всегда возвращают все в одном ответе с has_more: false.

Неправильно сформированный курсор или курсор, указывающий за конец списка, отвечает кодом 400 validation_error.

Создайте версию вашей интеграции API Notiondesk

Отправьте необязательный заголовок nd-version, чтобы указать версию контракта, для которой была написана ваша интеграция:

nd-version: 2026-10-16

• Без заголовка запрос использует текущую версию.

• В каждом ответе в заголовке nd-version указывается версия, которая использовалась для ответа.

• Неизвестное значение отвечает 400 invalid_version.

Новые маршруты, новые необязательные параметры и новые поля ответа поставляются без обновления версии. Ваша интеграция должна игнорировать поля, которые она не распознает, поэтому новое поле никогда не приведет к сбою.

Примечание: Закрепите в рабочем коде. В этом случае ваша интеграция сохранит поведение, которое было протестировано, даже если в будущей версии изменится ответ.nd-version

Правила именования

• Названия полей в запросах и ответах имеют формат snake_case : page_size, next_cursor, default_locale.

• Параметры запроса имеют одно написание. ?page_size=10 работает. ?pageSize=10 отклоняется как неизвестный параметр с кодом ошибки 400 validation_error.

• Неизвестные параметры и поля тела запроса отклоняются с кодом 400 validation_error, поэтому опечатка никогда не проходит незаметно.

• API использует собственные существительные. Центр поддержки обозначается как site, а коллекция — как category. Пути выглядят как /sites/{site_id}/categories.

• Даты указаны в формате ISO 8601 , например, 2026-10-18T14:39:03+00:00.

Часто задаваемые вопросы

Что дальше?

• Обработка ошибок API Notiondesk, ограничений скорости и повторных попыток.

• Читайте статьи, подборки и записи об изменениях с помощью API Notiondesk

• Начните работу с REST API Notiondesk