citely-api (khuyến nghị)
Citely tự host nội dung — website chỉ là reader, không cần backend/receiver.
Dùng khi: bạn chỉ muốn có bài trên site, KHÔNG muốn dựng/duy trì backend (DB, endpoint, xác thực webhook). Đây là mặc định khuyến nghị cho site mới.
Khác mọi adapter khác, citely-api không có receiver. Citely lưu bài đã enrich (HTML +
JSON-LD + meta + i18n) và phục vụ qua read-API. Website của bạn chỉ là một reader: fetch
bài rồi render dưới domain của bạn. Không HMAC, không DB, không build-server.
Bất đối xứng: db/fs-build = Citely push vào site (site có receiver). citely-api = site pull từ Citely (site có reader). Vì thế không có bước handshake GET/POST receiver ở đây.
Chuẩn bị (làm 1 lần)
- Trong Citely: Sites → Connect → "Citely-hosted (read-API)" → tạo site.
- Citely hiện: một site token công khai (dùng trong URL) + một read-key bí mật
(Bearer). Đặt read-key vào env phía server là
CITELY_READ_KEY(KHÔNG lộ xuống browser). - Publish bài như bình thường trong Citely → bài xuất hiện tức thì trên read-API.
Đọc bài
Base URL: https://citely-seo.com/connect/v1/sites/{siteToken}
| Method + path | Auth | Trả về |
|---|---|---|
GET /posts/{slug} | công khai (cache CDN) | 1 bài |
GET /posts?limit=&cursor= | Bearer <read-key> | list phân trang |
GET /export | Bearer <read-key> | toàn bộ bài (chống lock-in) |
Chi tiết field, phân trang, mã lỗi: Read-API reference.
Dựng reader
- SSG (Astro / Next export / Hugo): build-time fetch
GET /posts(kèm read-key, server-side) → nạp slug vàogenerateStaticParams→ fetch từngGET /posts/{slug}. Rebuild theo lịch hoặc qua deploy hook để nhận bài mới. - SSR (Next SSR / Laravel / Rails): fetch
GET /posts/{slug}mỗi request (public + edge-cache nên rẻ); trang list dùngGET /postsserver-side với read-key. - Render
htmlas-is; mỗijsonLd[]→<script type="application/ld+json">trong<head>. Đặt<link rel="canonical">về URL của CHÍNH bạn. - Song ngữ: gom bài cùng
translationKey, nối<link rel="alternate" hreflang>.
Cache & độ sẵn sàng
Read-API đứng sau Cloudflare CDN (Cache Everything + s-maxage + stale-while-revalidate
- Always Online): phần lớn read hứng ở edge. Khi bài được publish/sửa, Citely purge cache URL bài + list → bạn luôn thấy bản mới.
Nội dung publish nằm trên web công khai → mục tiêu bảo mật là chống enumeration + abuse (Bearer + rate-limit + token khó đoán), KHÔNG hứa "giấu nội dung".