בקשות API לעמודים וגירסה Notiondesk

כל רשימת API Notiondesk משתמשת באותו עמוד סמן, וכל בקשה יכולה להצמיד את גרסת ה-API שלשמה נכתבה האינטגרציה שלך באמצעות הכותרת nd-version. מאמר זה מסביר כיצד פועל עמוד ה-API Notiondesk, כיצד לקרוא כל עמוד ברשימה, כיצד פועל ניהול גרסאות API, וכללי מתן שמות לשדות ופרמטרים.

כיצד פועל חלוקת דפים ב-API של Notiondesk

כל מסלול רשימה עונה על אותה מעטפת:

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

שלוט בדף באמצעות שני פרמטרי שאילתה:

רשימות אינן נושאות מספרי עמודים ואין ספירה כוללת.

קרא כל עמוד ברשימה

חזור על הבקשה כאשר cursor מוגדר ל-next_cursor של התגובה הקודמת עד ש-has_more יהיה false.

העמוד הראשון:

העמוד הבא, כאשר NEXT_CURSOR מוחלף על ידי next_cursor המקודד על ידי כתובת האתר של העמוד הראשון:

אותה לולאה ב-JavaScript:

ובפיתון:

כללי הסמן

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.

סמן בעל מבנה פגום, או סמן שמצביע מעבר לסוף הרשימה, עונה על 400 validation_error.

גרסה של אינטגרציית ה-API Notiondesk שלך

שלח את הכותרת האופציונלית nd-version כדי להצמיד את גרסת החוזה שלגביה נכתבה האינטגרציה שלך:

nd-version: 2026-10-16

• ללא הכותרת, הבקשה משתמשת בגרסה הנוכחית.

• כל תגובה מציינת את הגרסה שענתה עליה בכותרת nd-version משלה.

• ערך לא ידוע עונה על 400 invalid_version.

נתיבים חדשים, פרמטרים אופציונליים חדשים ושדות תגובה חדשים נשלחים ללא גרסה חדשה. האינטגרציה שלך חייבת להתעלם משדות שהיא לא מזהה, כך ששדה חדש לעולם לא יפר אותה.

הערה: יש להצמיד לקוד הייצור. האינטגרציה שלך שומרת לאחר מכן את ההתנהגות שנבדקה כנגדה כאשר גרסה עתידית משנה תגובה.nd-version

כללי מתן שמות

• שמות השדות הם snake_case בבקשות ובתגובות: page_size, next_cursor, default_locale.

• לפרמטרי שאילתה יש איות אחד. ?page_size=10 עובד. ?pageSize=10 נדחה כפרמטר לא ידוע עם 400 validation_error.

• פרמטרים ושדות גוף לא ידועים נדחים עם 400 validation_error, כך ששגיאת הקלדה לעולם לא תעבור בשקט.

• ממשק ה-API משתמש בשמות עצם משלו. מרכז עזרה הוא site, ואוסף הוא category. נתיבים נראים כך: /sites/{site_id}/categories.

• התאריכים הם לפי תקן ISO 8601 , לדוגמה 2026-10-18T14:39:03+00:00.

שאלות נפוצות

מה הלאה

• טיפול בשגיאות API, מגבלות קצב וניסיונות חוזרים של Notiondesk

• קרא מאמרים, אוספים ורשומות ביומן שינויים בעזרת ממשק ה-API Notiondesk

• התחל עם ממשק ה-API של REST Notiondesk