REST và GraphQL

KDIGI CMS là headless: trang quản trị ở /admin, còn website công khai là frontend bạn tự chọn (Next.js, Astro, Nuxt, PHP…). Frontend lấy nội dung qua REST hoặc GraphQL do Payload cung cấp sẵn.

REST

Mỗi collection có một endpoint /api/<collection>:

# 5 bài viết mới nhất của một site
curl "https://cms.example.com/api/posts?where[tenant][equals]=<site-id>&sort=-publishedAt&limit=5"

# một bài theo slug
curl "https://cms.example.com/api/posts?where[tenant][equals]=<site-id>&where[slug][equals]=chao-the-gioi"

Các collection nội dung chính: posts, pages, products, landings, taxonomies, menus, faqs, authors, redirects, media, sites. Tham số truy vấn của Payload (where, sort, limit, page, depth, locale) dùng bình thường.

GraphQL

Endpoint /api/graphql. Trình playground bị tắt ở production và độ phức tạp truy vấn bị giới hạn. Lưu ý: việc render Markdown sang HTML chỉ áp dụng cho REST, nên consumer GraphQL cần tự xử lý trường *Md.

Quy ước cần nhớ

• Luôn lọc theo site. Đọc công khai không tự lọc site, bạn phải thêm where[tenant][equals]=<site-id>. Xem Nhiều website.
• Chỉ nội dung đã xuất bản mới trả về cho khách ẩn danh: trạng thái published và đã đến giờ đăng.
• Markdown đã render. REST trả HTML ở trường gốc (content), nguồn Markdown nằm ở trường contentMd. Shortcode đã được mở rộng. Xem Soạn thảo Markdown.
• SEO: seo.title và seo.description rỗng nghĩa là dùng mẫu của site; frontend thay biến khi dựng thẻ. seo.jsonLd là đồ thị JSON-LD dựng sẵn. Xem SEO và JSON-LD.
• Ngôn ngữ: nội dung mặc định vi, có en; truyền locale để chọn, bản thiếu sẽ fallback.
• Menu trả về dạng cây trong items.
• Site config: collection sites đọc công khai nhưng khoá bí mật (R2…) không bao giờ lộ ra.

Xác thực

Đọc nội dung đã xuất bản không cần đăng nhập. Để đọc bản nháp hoặc ghi dữ liệu, dùng tài khoản và API key của người dùng:

curl -H "Authorization: users API-Key <api-key>" "https://cms.example.com/api/posts?where[status][equals]=draft"

Tạo API key trong hồ sơ người dùng ở trang quản trị. Quyền của key giống quyền của vai trò người đó. Xem Vai trò và phân quyền.

Bình luận và làm mới cache

• Gửi bình luận qua endpoint riêng POST /api/comments/create (cần postId hoặc productId và khoá site), mặc định ở trạng thái chờ duyệt. Đặt RECAPTCHA_SECRET để bật xác minh reCAPTCHA.
• Mỗi lần lưu nội dung, CMS xếp job gọi POST https://<tên miền site>/api/cms/revalidate để frontend làm mới cache. Cần ENABLE_JOBS_AUTORUN=true trên một instance.

Quy ước đầy đủ ở REST API reference (tiếng Anh).