Paginierung und Versions-API-Anfragen Notiondesk

Jede Notiondesk-API-Liste verwendet dieselbe Cursor-Paginierung, und jede Anfrage kann die API-Version, für die Ihre Integration entwickelt wurde, mithilfe des nd-version-Headers festlegen. Dieser Artikel erklärt die Funktionsweise der Notiondesk-API-Paginierung, das Lesen jeder Seite einer Liste, die API-Versionsverwaltung sowie die Namensregeln für Felder und Parameter.

Wie die Paginierung der Notiondesk API funktioniert

Jede Listenroute beantwortet denselben Umschlag:

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

Die Seite wird mit zwei Abfrageparametern gesteuert:

Listen enthalten keine Seitenzahlen und keine Gesamtanzahl.

Lies jede Seite einer Liste

Wiederhole die Anfrage, wobei cursor auf den Wert von next_cursor der vorherigen Antwort gesetzt ist, bis has_more gleich false ist.

Die erste Seite:

Die nächste Seite, auf der NEXT_CURSOR durch das URL-codierte next_cursor der ersten Seite ersetzt wurde:

Die gleiche Schleife in JavaScript:

Und in Python:

Cursorregeln

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

• Der Cursor ist undurchsichtig. Bitte analysieren Sie ihn nicht und erstellen Sie auch keinen eigenen. Geben Sie ihn exakt so zurück, wie Sie ihn erhalten haben.

• Sie können page_size zwischen den Seiten ändern. Die nächste Seite beginnt dort, wo die vorherige aufgehört hat.

• Der Cursor speichert eine Position, keine Momentaufnahme. Wenn beim Blättern ein Element hinzugefügt oder entfernt wird, kann sich die Reihenfolge der nachfolgenden Elemente ändern, sodass eine Seite wiederholt werden oder ein Element übersprungen werden kann. Falls Ihre Integration Elemente löscht, während diese aufgelistet werden, beginnen Sie anschließend wieder auf der ersten Seite.

• Manche Listen enden frühzeitig. Die Änderungsliste umfasst maximal die 1.000 neuesten Einträge. Seitenweiterleitungen und Feedback umfassen maximal die 10.000 neuesten Einträge. Jenseits dieser Grenze wird has_more zu false.

• Manche Listen werden nie paginiert. Themes und Integrationen geben immer alles in einer Antwort zurück, mit has_more: false.

Ein fehlerhafter Cursor oder ein Cursor, der über das Ende der Liste hinaus zeigt, gibt die Antwort 400 validation_error.

Versionieren Sie Ihre Notiondesk API-Integration

Senden Sie den optionalen Header nd-version, um die Vertragsversion festzulegen, für die Ihre Integration geschrieben wurde:

nd-version: 2026-10-16

• Ohne den Header verwendet die Anfrage die aktuelle Version.

• Jede Antwort gibt in ihrem eigenen nd-version-Header die Version an, die die Frage beantwortet hat.

• Ein unbekannter Wert gibt 400 invalid_version zurück.

Neue Routen, neue optionale Parameter und neue Antwortfelder werden ohne neue Version bereitgestellt. Ihre Integration muss unbekannte Felder ignorieren, damit ein neues Feld niemals zu Problemen führt.

Hinweis: Fixieren Sie dies im Produktionscode. Ihre Integration behält dann das getestete Verhalten bei, auch wenn eine zukünftige Version die Antwort ändert.nd-version

Namensregeln

• Die Feldnamen sind in Anfragen und Antworten in snake_case geschrieben : page_size, next_cursor, default_locale.

• Die Abfrageparameter haben nur eine Schreibweise. ?page_size=10 funktioniert. ?pageSize=10 wird als unbekannter Parameter mit dem Fehlercode 400 abgelehnt. validation_error.

• Unbekannte Parameter und Felder im Nachrichtentext werden mit dem Fehlercode 400 validation_error zurückgewiesen , sodass ein Tippfehler niemals unbemerkt bleibt.

• Die API verwendet eigene Nomen. Ein Hilfezentrum ist ein site, eine Sammlung ein category. Pfade sehen wie /sites/{site_id}/categories aus.

• Datumsangaben erfolgen im ISO 8601-Format , zum Beispiel 2026-10-18T14:39:03+00:00.

Häufig gestellte Fragen

Was kommt als Nächstes?

• Behandelt API-Fehler, Ratenbegrenzungen und Wiederholungsversuche der Klasse Notiondesk

• Lesen Sie Artikel, Sammlungen und Änderungsprotokolleinträge mit der Notiondesk API.

• Legen Sie los mit der Notiondesk REST-API.