Richieste API di impaginazione e versione Notiondesk

Ogni elenco API Notiondesk utilizza la stessa paginazione del cursore e ogni richiesta può specificare la versione API con cui è stata scritta l'integrazione tramite l'intestazione nd-version. Questo articolo spiega come funziona la paginazione API Notiondesk, come leggere tutte le pagine di un elenco, come funziona il versioning API e le regole di denominazione per campi e parametri.

Come funziona la paginazione dell'API Notiondesk

Ogni percorso di elenco risponde alla stessa domanda:

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

Controlla la pagina con due parametri di query:

Gli elenchi non riportano numeri di pagina né il conteggio totale.

Leggi ogni pagina di una lista

Ripeti la richiesta con cursor impostato su next_cursor della risposta precedente finché has_more non è false.

La prima pagina:

La pagina successiva, con NEXT_CURSOR sostituito da next_cursor codificato in URL della prima pagina:

Lo stesso ciclo in JavaScript:

E in Python:

Regole del cursore

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

• Il cursore è opaco. Non analizzarlo né crearne uno tu stesso. Restituiscilo esattamente come lo hai ricevuto.

• È possibile modificare page_size tra le pagine. La pagina successiva inizia dove termina la precedente.

• Il cursore memorizza una posizione, non un'istantanea. L'aggiunta o la rimozione di un elemento durante la paginazione può spostare gli elementi successivi, pertanto una pagina può ripetere o saltare un elemento. Se l'integrazione elimina elementi mentre li elenca, ricomincia dalla prima pagina.

• Alcuni elenchi si interrompono prima. L'elenco del registro delle modifiche raggiunge al massimo le 1.000 voci più recenti. I reindirizzamenti di pagina e i feedback raggiungono al massimo le 10.000 voci più recenti. Oltre tale limite, has_more diventa false.

• Alcuni elenchi non vengono mai impaginati. I temi e le integrazioni restituiscono sempre tutto in un'unica risposta, con has_more: false.

Un cursore non valido, ovvero un cursore che punta oltre la fine dell'elenco, restituisce 400 validation_error.

Versione dell'integrazione API Notiondesk

Invia l'intestazione facoltativa nd-version per bloccare la versione del contratto rispetto alla quale è stata scritta l'integrazione:

nd-version: 2026-10-16

• Senza l'intestazione, la richiesta utilizza la versione corrente.

• Ogni risposta indica la versione che l'ha fornita nella propria intestazione nd-version.

• Un valore sconosciuto risponde 400 invalid_version.

Nuove rotte, nuovi parametri opzionali e nuovi campi di risposta vengono rilasciati senza una nuova versione. La tua integrazione deve ignorare i campi che non riconosce, quindi un nuovo campo non la renderà mai incompatibile.

Nota: Blocca nel codice di produzione. In questo modo, l'integrazione manterrà il comportamento testato anche quando una versione futura modificherà la risposta.nd-version

Regole di denominazione

• I nomi dei campi sono in formato snake_case nelle richieste e nelle risposte: page_size, next_cursor, default_locale.

• I parametri di query hanno una sola ortografia. ?page_size=10 funziona. ?pageSize=10 viene rifiutato come parametro sconosciuto con 400 validation_error.

• I parametri e i campi del corpo sconosciuti vengono rifiutati con 400 validation_error, quindi un errore di battitura non passa mai inosservato.

• L'API utilizza i propri sostantivi. Un centro assistenza è un site e una raccolta è un category. I percorsi hanno la forma /sites/{site_id}/categories.

• Le date sono in formato ISO 8601 , ad esempio 2026-10-18T14:39:03+00:00.

Domande frequenti

Cosa succederà dopo?

• Gestire gli errori dell'API Notiondesk, i limiti di frequenza e i tentativi di ripetizione.

• Leggi articoli, raccolte e voci del registro delle modifiche con l'API Notiondesk

• Inizia a utilizzare l'API REST Notiondesk