Bắt đầu nhanh

Bạn cần: mã trang web (siteSlug) do đội ngũ i-Catholic cấp (xem Tổng quan). Không cần khóa API hay đăng nhập. Các ví dụ dưới đây dùng giao-xu-cua-ban; hãy thay bằng mã của bạn.

1. Gọi thử

curl -s "https://api.i-catholic.org/v2/public/cms/giao-xu-cua-ban/site?locale=vi"

Phản hồi có dạng { "data": { ... } } (rút gọn):

{
  "data": {
    "slug": "giao-xu-cua-ban",
    "primaryLocale": "vi",
    "locales": ["vi", "en"],
    "locale": "vi",
    "info": { "name": "Giáo xứ Của Bạn", "address": "...", "phones": ["..."], "...": "..." },
    "categories": [{ "slug": "tin-tuc", "parent": null, "name": "Tin tức", "position": 0 }],
    "tags": [{ "slug": "gioi-tre", "name": "Giới trẻ" }],
    "menus": { "primary": [], "footer": [] }
  }
}

Nếu nhận 404 với "message": "Not found": mã trang web sai, trang web chưa được bật, hoặc ngôn ngữ bạn hỏi chưa bật cho trang web này. Ba trường hợp này cố ý trả về giống hệt nhau.

2. Danh sách bài và một bài viết

Đoạn mã dưới đây chạy được cả trong trình duyệt lẫn Node 18+ (đều có fetch):

const API = 'https://api.i-catholic.org/v2/public/cms/giao-xu-cua-ban'

async function getJson<T>(url: string): Promise<T> {
  // No headers, no credentials: a CORS "simple request" (see the performance page).
  const res = await fetch(url, { credentials: 'omit' })
  if (!res.ok) throw new Error(`CMS ${res.status}: ${url}`)
  return res.json() as Promise<T>
}

// 12 newest posts in Vietnamese (featured ones first). Keep the key order: locale, …, page, limit.
const list = await getJson<{ data: Array<{ slug: string; title: string; excerpt: string }>; meta: { pageCount: number } }>(
  `${API}/entries?locale=vi&page=1&limit=12`,
)
for (const post of list.data) console.log(post.slug, post.title)

// One post (or page) by slug.
const { data: entry } = await getJson<{ data: { slug: string; title: string; bodyHtml: string } }>(
  `${API}/entries/${encodeURIComponent(list.data[0].slug)}?locale=vi`,
)
console.log(entry.title)

Ba điều cần nhớ ngay từ đầu:

1. locale, page, limit là bắt buộc khi lấy danh sách, và limit chỉ nhận 3, 6, 12, 24 hoặc 100. Giá trị khác bị từ chối với 400.
2. Giữ đúng thứ tự tham số: locale, category, tag, q, sort, page, limit. Bộ đệm (cache) khóa theo đúng chuỗi URL; viết khác thứ tự thì sau khi nhân sự sửa bài, trang của bạn có thể hiện bản cũ thêm tới 60 giây.
3. bodyHtml là HTML. Máy chủ đã lọc nó theo một danh sách thẻ an toàn, nhưng hãy lọc thêm một lần ở phía bạn trước khi chèn vào trang (xem Tham chiếu API).

3. Tiếp theo

• Đọc Tham chiếu API để biết đủ các trường.
• Trang web nhiều ngôn ngữ: Đa ngôn ngữ và đường dẫn.
• Trước khi đưa lên chạy thật: Hiệu năng, cache, giới hạn và lỗi.