Paginatie en versie Notiondesk API-verzoeken

Elke API-lijst van Notiondesk gebruikt dezelfde cursorpaginering en elk verzoek kan de API-versie waarop uw integratie is gebaseerd vastleggen met de header nd-version. Dit artikel legt uit hoe API-paginering van Notiondesk werkt, hoe u elke pagina van een lijst kunt lezen, hoe API-versiebeheer werkt en de naamgevingsregels voor velden en parameters.

Hoe werkt de paginering van de Notiondesk API?

Elke lijstroute beantwoordt dezelfde envelop:

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

Beheer de pagina met twee queryparameters:

Lijsten bevatten geen paginanummers en geen totaal aantal.

Lees elke pagina van een lijst.

Herhaal het verzoek met cursor ingesteld op de next_cursor van het vorige antwoord totdat has_more gelijk is aan false.

De eerste pagina:

De volgende pagina, waarbij NEXT_CURSOR is vervangen door de URL-gecodeerde next_cursor van de eerste pagina:

Dezelfde lus in JavaScript:

En in Python:

Cursorregels

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

• De cursor is ondoorzichtig. Parseer hem niet en maak er zelf geen aan. Geef hem precies zo terug als je hem hebt ontvangen.

• Je kunt page_size tussen pagina's wijzigen. De volgende pagina begint waar de vorige eindigde.

• Een cursor houdt een positie vast, geen momentopname. Een item dat wordt toegevoegd of verwijderd tijdens het laden van de pagina kan de items erna verschuiven, waardoor een pagina een item kan herhalen of overslaan. Als uw integratie items verwijdert terwijl ze worden weergegeven, begin dan daarna opnieuw vanaf de eerste pagina.

• Sommige lijsten stoppen voortijdig. De lijst met wijzigingen bevat maximaal de 1000 nieuwste items. Pagina-omleidingen en feedback bevatten maximaal de 10.000 nieuwste items. Na die limiet wordt has_more false.

• Sommige lijsten worden nooit gepagineerd. Thema's en integraties retourneren altijd alles in één reactie, met has_more: false.

Een onjuist gevormde cursor, of een cursor die voorbij het einde van de lijst wijst, geeft als antwoord 400 validation_error.

Versiebeheer van uw Notiondesk API-integratie

Verzend de optionele header nd-version om de contractversie vast te leggen waarop uw integratie is gebaseerd:

nd-version: 2026-10-16

• Zonder de header gebruikt het verzoek de huidige versie.

• Elk antwoord vermeldt in de koptekst nd-version welke versie het antwoord heeft gegeven.

• Een onbekende waarde geeft als antwoord 400 invalid_version.

Nieuwe routes, nieuwe optionele parameters en nieuwe responsvelden worden zonder nieuwe versie geleverd. Uw integratie moet velden negeren die niet worden herkend, zodat een nieuw veld de integratie nooit beschadigt.

Opmerking: Zet dit vast in de productiecode. Je integratie behoudt dan het gedrag waarop het is getest, zelfs als een toekomstige versie de respons wijzigt.nd-version

Naamgevingsregels

• Veldnamen worden in verzoeken en antwoorden in snake_case-stijl weergegeven : page_size, next_cursor, default_locale.

• Queryparameters hebben slechts één spelling. ?page_size=10 werkt. ?pageSize=10 wordt afgewezen als een onbekende parameter met foutcode 400 validation_error.

• Onbekende parameters en velden in de body worden afgewezen met 400 validation_error, dus een typefout wordt nooit ongemerkt doorgelaten.

• De API gebruikt eigen termen. Een helpcentrum is een site, en een collectie is een category. Paden zien eruit als /sites/{site_id}/categories.

• Datums worden weergegeven volgens ISO 8601 , bijvoorbeeld 2026-10-18T14:39:03+00:00.

Veelgestelde vragen

Wat volgt?

• Verwerk API-fouten, snelheidslimieten en herhaalpogingen voor Notiondesk.

• Lees artikelen, collecties en wijzigingslogboeken met de Notiondesk API

• Ga aan de slag met de Notiondesk REST API