ページネーションとバージョン Notiondesk API リクエスト

すべての Notiondesk API リストは同じカーソルページネーションを使用し、すべてのリクエストで nd-version ヘッダーを使用して、統合が作成された API バージョンを固定できます。この記事では、Notiondesk API ページネーションの仕組み、リストの各ページを読み取る方法、API バージョニングの仕組み、フィールドとパラメーターの命名規則について説明します。

Notiondesk APIのページネーションの仕組み

すべてのリストルートは同じ封筒に応答します。

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

2つのクエリパラメータを使用してページを制御します。

リストにはページ番号も総数も記載されていません。

リストのすべてのページを読む

has_more が false になるまで、cursor を前回のレスポンスの next_cursor に設定してリクエストを繰り返します。

最初のページ：

次のページでは、NEXT_CURSOR が最初のページの URL エンコードされた next_cursor に置き換えられています。

JavaScriptでの同じループ：

Pythonでは次のようになります。

カーソルルール

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

• カーソルは不透明です。解析したり、自分で作成したりしないでください。受け取ったままの状態で返してください。

• ページ間で「page_size」の値を変更できます。次のページは前のページの終了位置から始まります。

• カーソルは位置を保持するものであり、スナップショットを保持するものではありません。ページ操作中に項目が追加または削除されると、その後の項目がずれる可能性があるため、ページ内で項目が繰り返されたり、スキップされたりすることがあります。統合処理で項目が一覧表示されている間に削除された場合は、その後最初のページからやり直してください。

• リストによっては途中で停止するものがあります。変更履歴リストは最大で最新の1,000件までしか表示されません。ページのリダイレクトとフィードバックは最大で最新の10,000件までしか表示されません。この制限を超えると、has_moreはfalseになります。

• 一部のリストはページングされません。テーマと統合機能は常にすべてを has_more: false 付きで 1 つのレスポンスで返します。

不正なカーソル、またはリストの末尾を超えたカーソルの場合、400 validation_error と回答されます。

Notiondesk API統合のバージョン

オプションの nd-version ヘッダーを送信して、統合が作成された際の契約バージョンを固定します。

nd-version: 2026-10-16

• ヘッダーがない場合、リクエストは現在のバージョンを使用します。

• すべての応答には、その応答を行ったバージョンが独自の nd-version ヘッダーに記載されています。

• 不明な値には 400 invalid_version と答えます。

新しいルート、新しいオプションパラメータ、新しいレスポンスフィールドは、バージョンアップなしで提供されます。統合システムは認識できないフィールドを無視するように設定されているため、新しいフィールドが追加されてもシステムが壊れることはありません。

注：本番コードでピン留めしてください。そうすることで、将来のバージョンでレスポンスが変更された場合でも、統合機能はテスト時の動作を維持できます。nd-version

命名規則

• リクエストとレスポンスのフィールド名はスネークケースです: page_size、next_cursor、default_locale。

• クエリパラメータにはスペルが1つしかありません。__ PRESERVED_17__ は機能します。?pageSize=10 は不明なパラメータとして拒否され、エラーコードは 400 validation_error となります。

• 不明なパラメータや本文フィールドは400 validation_errorで拒否されるため、タイプミスが黙って通過することはありません。

• API は独自の名称を使用します。ヘルプ センターは site、コレクションは category です。パスは /sites/{site_id}/categories のようになります。

• 日付はISO 8601形式です。例えば、2026-10-18T14:39:03+00:00 のようになります。

よくある質問

次は？

• Notiondesk APIエラー、レート制限、および再試行を処理する

• Notiondesk API を使用して、記事、コレクション、変更履歴エントリを読み取ります。

• Notiondesk REST API を使い始めましょう