Phân trang và phiên bản Notiondesk Yêu cầu API

Mọi danh sách API Notiondesk đều sử dụng cùng một phân trang con trỏ, và mọi yêu cầu đều có thể ghim phiên bản API mà quá trình tích hợp của bạn được viết dựa trên đó bằng tiêu đề nd-version. Bài viết này giải thích cách hoạt động của phân trang API Notiondesk, cách đọc từng trang của danh sách, cách hoạt động của việc quản lý phiên bản API và các quy tắc đặt tên cho các trường và tham số.

Cách thức hoạt động của phân trang API Notiondesk

Mọi lộ trình trong danh sách đều trả lời cùng một câu hỏi:

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

Điều khiển trang bằng hai tham số truy vấn:

Danh sách không có số trang và không có tổng số.

Đọc kỹ từng trang của danh sách.

Lặp lại yêu cầu với cursor được đặt thành next_cursor của phản hồi trước đó cho đến khi has_more bằng false.

Trang đầu tiên:

Trang tiếp theo, với NEXT_CURSOR được thay thế bằng next_cursor đã được mã hóa URL của trang đầu tiên:

Vòng lặp tương tự trong JavaScript:

Và trong Python:

Quy tắc con trỏ

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

• Con trỏ này không rõ ràng. Không được phân tích cú pháp hoặc tự tạo con trỏ cho nó. Hãy trả lại con trỏ y nguyên như khi bạn nhận được.

• Bạn có thể thay đổi page_size giữa các trang. Trang tiếp theo bắt đầu từ vị trí trang trước kết thúc.

• Con trỏ chuột giữ vị trí, chứ không phải là ảnh chụp nhanh. Một mục được thêm hoặc xóa trong khi bạn đang chuyển trang có thể làm dịch chuyển các mục sau đó, vì vậy một trang có thể lặp lại hoặc bỏ qua một mục. Nếu hệ thống tích hợp của bạn xóa các mục trong khi đang liệt kê chúng, hãy bắt đầu lại từ trang đầu tiên sau đó.

• Một số danh sách dừng sớm. Danh sách nhật ký thay đổi chỉ hiển thị tối đa 1.000 mục mới nhất. Danh sách chuyển hướng trang và phản hồi chỉ hiển thị tối đa 10.000 mục mới nhất. Vượt quá giới hạn đó, has_more sẽ trở thành false.

• Một số danh sách không bao giờ phân trang. Các chủ đề và tích hợp luôn trả về mọi thứ trong một phản hồi duy nhất, với has_more: false.

Con trỏ bị lỗi định dạng, hoặc con trỏ trỏ vượt quá cuối danh sách, sẽ trả về lỗi 400 validation_error.

Phiên bản tích hợp API Notiondesk của bạn

Gửi tiêu đề tùy chọn nd-version để cố định phiên bản hợp đồng mà quá trình tích hợp của bạn được viết dựa trên đó:

nd-version: 2026-10-16

• Nếu không có phần tiêu đề, yêu cầu sẽ sử dụng phiên bản hiện tại.

• Mỗi câu trả lời đều ghi rõ phiên bản đã trả lời trong tiêu đề nd-version của riêng nó.

• Một giá trị không xác định trả lời 400 invalid_version.

Các tuyến đường mới, các tham số tùy chọn mới và các trường phản hồi mới được cung cấp mà không cần phiên bản mới. Quá trình tích hợp của bạn phải bỏ qua các trường mà nó không nhận ra, vì vậy một trường mới sẽ không bao giờ gây lỗi.

Lưu ý: Ghim mã vào mã sản xuất. Khi đó, quá trình tích hợp của bạn sẽ giữ nguyên hành vi đã được kiểm thử khi phiên bản tương lai thay đổi phản hồi.nd-version

Quy tắc đặt tên

• Tên trường được viết theo kiểu snake_case trong yêu cầu và phản hồi: page_size, next_cursor, default_locale.

• Các tham số truy vấn chỉ có một cách viết. ?page_size=10 hoạt động. ?pageSize=10 bị từ chối vì là tham số không xác định với mã lỗi 400 validation_error.

• Các tham số và trường dữ liệu không xác định sẽ bị từ chối với mã lỗi 400 validation_error, do đó lỗi chính tả sẽ không bao giờ được bỏ qua mà không bị phát hiện.

• API sử dụng các danh từ riêng của nó. Trung tâm trợ giúp là một site, và bộ sưu tập là một category. Đường dẫn trông giống như /sites/{site_id}/categories.

• Ngày tháng được định dạng theo ISO 8601 , ví dụ: 2026-10-18T14:39:03+00:00.

Câu hỏi thường gặp

Tiếp theo là gì?

• Xử lý các lỗi API, giới hạn tỷ lệ và các lần thử lại của Notiondesk

• Đọc các bài viết, bộ sưu tập và mục nhật ký thay đổi bằng API Notiondesk

• Bắt đầu sử dụng API REST Notiondesk