Paginar e versão Notiondesk solicitações de API

Todas as listas da API Notiondesk usam a mesma paginação por cursor, e cada requisição pode fixar a versão da API para a qual sua integração foi escrita com o cabeçalho nd-version. Este artigo explica como funciona a paginação da API Notiondesk, como ler cada página de uma lista, como funciona o versionamento da API e as regras de nomenclatura para campos e parâmetros.

Como funciona a paginação da API Notiondesk

Cada rota de lista responde ao mesmo envelope:

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

Controle a página com dois parâmetros de consulta:

As listas não contêm números de página nem uma contagem total.

Leia cada página de uma lista

Repita a solicitação com cursor definido como o next_cursor da resposta anterior até que has_more seja false.

A primeira página:

A próxima página, com NEXT_CURSOR substituído pelo next_cursor codificado em URL da primeira página:

O mesmo loop em JavaScript:

E em Python:

Regras do cursor

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

• O cursor é opaco. Não o analise nem crie um novo. Devolva-o exatamente como o recebeu.

• Você pode alterar o valor de page_size entre as páginas. A próxima página começa onde a anterior terminou.

• O cursor representa uma posição, não uma captura instantânea. Um item adicionado ou removido durante a rolagem pode deslocar os itens subsequentes, permitindo que uma página repita ou pule um item. Se a sua integração excluir itens durante a listagem, recomece a rolagem a partir da primeira página.

• Algumas listas param antes do limite. A lista de changelog atinge, no máximo, as 1.000 entradas mais recentes. Redirecionamentos de página e feedback atingem, no máximo, as 10.000 entradas mais recentes. Após esse limite, has_more torna-se false.

• Algumas listas nunca são paginadas. Temas e integrações sempre retornam tudo em uma única resposta, com has_more: false.

Um cursor malformado, ou um que aponta para além do final da lista, retorna 400 validation_error.

Versionar sua integração de API Notiondesk

Envie o cabeçalho opcional nd-version para fixar a versão do contrato com a qual sua integração foi escrita:

nd-version: 2026-10-16

• Sem o cabeçalho, a solicitação utiliza a versão atual.

• Cada resposta indica a versão que a respondeu em seu próprio cabeçalho nd-version.

• Um valor desconhecido responde 400 invalid_version.

Novas rotas, novos parâmetros opcionais e novos campos de resposta são distribuídos sem a necessidade de uma nova versão. Sua integração deve ignorar campos que não reconhece, portanto, um novo campo nunca a quebrará.

Observação: fixe o código em produção. Dessa forma, sua integração manterá o comportamento testado mesmo quando uma versão futura alterar a resposta.nd-version

Regras de nomenclatura

• Os nomes dos campos estão em snake_case nas solicitações e respostas: page_size, next_cursor, default_locale.

• Os parâmetros de consulta têm uma única grafia. ?page_size=10 funciona. ?pageSize=10 é rejeitado como um parâmetro desconhecido com código 400. validation_error

• Parâmetros e campos de corpo desconhecidos são rejeitados com 400 validation_error, portanto, um erro de digitação nunca passa despercebido.

• A API usa seus próprios substantivos. Uma central de ajuda é um site, e uma coleção é um category. Os caminhos têm a aparência de /sites/{site_id}/categories.

• As datas estão em conformidade com a norma ISO 8601 , por exemplo, 2026-10-18T14:39:03+00:00.

Perguntas frequentes

O que vem a seguir?

• Lidar com erros da API Notiondesk, limites de taxa e novas tentativas.

• Leia artigos, coleções e entradas do changelog com a API Notiondesk

• Comece a usar a API REST Notiondesk