Paginacja i wersja Notiondesk żądań API

Każda lista API Notiondesk korzysta z tej samej paginacji kursora, a każde żądanie może przypisać wersję API, dla której napisano integrację, za pomocą nagłówka nd-version. W tym artykule wyjaśniono, jak działa paginacja API Notiondesk, jak odczytać każdą stronę listy, jak działa wersjonowanie API oraz zasady nazewnictwa pól i parametrów.

Jak działa paginacja API Notiondesk

Każda trasa listy odpowiada tej samej kopercie:

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

Kontroluj stronę za pomocą dwóch parametrów zapytania:

Listy nie zawierają numerów stron ani łącznej liczby sztuk.

Przeczytaj każdą stronę listy

Powtórz żądanie z wartością cursor ustawioną na wartość next_cursor z poprzedniej odpowiedzi, aż wartość has_more będzie równa false.

Pierwsza strona:

Następna strona, na której NEXT_CURSOR zastąpiono zakodowanym w adresie URL next_cursor z pierwszej strony:

Ta sama pętla w JavaScript:

A w Pythonie:

Reguły kursora

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"]

• Kursor jest nieprzezroczysty. Nie analizuj go ani nie twórz samodzielnie. Przekaż go z powrotem dokładnie w takiej formie, w jakiej go otrzymałeś.

• Możesz zmieniać page_size między stronami. Następna strona zaczyna się tam, gdzie kończyła się poprzednia.

• Kursor zajmuje pozycję, a nie migawkę. Element dodany lub usunięty podczas przeglądania strony może przesuwać elementy po nim, dzięki czemu strona może powtarzać lub pomijać jeden element. Jeśli integracja usunie elementy podczas ich wyświetlania, zacznij od nowa od pierwszej strony.

• Niektóre listy kończą się przedwcześnie. Lista zmian obejmuje maksymalnie 1000 najnowszych wpisów. Przekierowania stron i informacje zwrotne obejmują maksymalnie 10 000 najnowszych wpisów. Powyżej tego limitu has_more to false.

• Niektóre listy nigdy nie są stronicowane. Motywy i integracje zawsze zwracają wszystko w jednej odpowiedzi, z has_more: false.

Nieprawidłowo sformatowany kursor lub taki, który wskazuje poza koniec listy, odpowiada 400 validation_error.

Wersja integracji API Notiondesk

Wyślij opcjonalny nagłówek nd-version, aby przypiąć wersję kontraktu, dla której została napisana Twoja integracja:

nd-version: 2026-10-16

• Bez nagłówka żądanie używa wersji bieżącej.

• W nagłówku nd-version każdej odpowiedzi podana jest wersja odpowiedzi.

• Nieznana wartość odpowiada 400 invalid_version.

Nowe trasy, nowe parametry opcjonalne i nowe pola odpowiedzi są dostarczane bez nowej wersji. Twoja integracja musi ignorować pola, których nie rozpoznaje, więc nowe pole nigdy jej nie zepsuje.

Uwaga: Przypnij w kodzie produkcyjnym. Twoja integracja zachowa wówczas zachowanie, które zostało przetestowane, gdy przyszła wersja zmieni odpowiedź.nd-version

Zasady nazewnictwa

• Nazwy pól w żądaniach i odpowiedziach są zapisane w formacie snake_case : page_size, next_cursor, default_locale.

• Parametry zapytania mają jedną pisownię. ?page_size=10 działa. ?pageSize=10 jest odrzucany jako nieznany parametr z 400 validation_error.

• Nieznane parametry i pola treści są odrzucane kodem 400 validation_error, więc literówka nigdy nie zostanie pominięta.

• API używa własnych rzeczowników. Centrum pomocy to site, a kolekcja to category. Ścieżki wyglądają tak: /sites/{site_id}/categories.

• Daty są w formacie ISO 8601 , na przykład 2026-10-18T14:39:03+00:00.

Często zadawane pytania

Co dalej?

• Obsługa błędów API Notiondesk, limitów szybkości i ponownych prób

• Czytaj artykuły, kolekcje i wpisy w dzienniku zmian za pomocą interfejsu API Notiondesk

• Rozpocznij korzystanie z interfejsu API REST Notiondesk