API là gì? Giải thích dễ hiểu cho người làm website

Đội ngũ KDIGIĐăng 03/11/202611 phút đọc

API (Application Programming Interface – giao diện lập trình ứng dụng) là một bộ quy tắc cho phép hai phần mềm nói chuyện với nhau: phần mềm A gửi một yêu cầu theo định dạng thống nhất, phần mềm B trả về dữ liệu hoặc thực hiện một hành động. Với người làm website, API là cách trang web lấy nội dung từ CMS, thanh toán, bản đồ hay email.

Tóm tắt nhanh

API giống người phục vụ trong nhà hàng: bạn (client) gọi món, bếp (server) nấu, người phục vụ (API) chuyển yêu cầu và mang món ra.

Web API phổ biến nhất hiện nay là REST (qua HTTP, trả JSON); ngoài ra có GraphQL, gRPC, SOAP, WebSocket.

Một request gồm: phương thức (GET/POST/PUT/PATCH/DELETE), URL, header, và đôi khi body; response có mã trạng thái (200, 201, 400, 401, 403, 404, 500…) và dữ liệu.

CMS headless là CMS "chỉ có API": nội dung được lấy qua REST/GraphQL để dựng website, app mobile hay bất kỳ kênh nào.

KDIGI CMS cung cấp REST và GraphQL; request ẩn danh chỉ đọc được nội dung đã xuất bản và REST trả sẵn HTML ở khóa content.

API là gì? Giải thích bằng ví dụ nhà hàng

Bạn ngồi ở bàn ăn và muốn gọi một tô phở. Bạn không vào bếp, không biết nồi nước dùng nằm ở đâu. Bạn nói với người phục vụ theo thực đơn: "một tô phở tái". Người phục vụ chuyển yêu cầu vào bếp, bếp làm xong và người phục vụ mang ra.

Bạn là client (trình duyệt, ứng dụng, website của bạn).
Bếp là server (hệ thống chứa dữ liệu và logic, ví dụ CMS).
Người phục vụ + thực đơn là API: nơi quy định bạn được gọi gì, gọi theo cách nào và nhận lại thứ gì.

Điểm mấu chốt: API là hợp đồng. Bạn không cần biết bên trong server viết bằng ngôn ngữ nào hay lưu dữ liệu ở đâu; chỉ cần tuân theo hợp đồng. Khi bên trong thay đổi nhưng hợp đồng giữ nguyên, ứng dụng của bạn vẫn chạy.

Web API hoạt động như thế nào?

Phần lớn API bạn gặp khi làm website là Web API chạy trên giao thức HTTP. Một lần gọi gồm hai nửa:

Request (yêu cầu)

Thành phần	Ý nghĩa	Ví dụ
Phương thức (method)	Bạn muốn làm gì	`GET` (đọc), `POST` (tạo), `PUT`/`PATCH` (sửa), `DELETE` (xóa)
URL / endpoint	Đối tượng bạn muốn thao tác	`https://cms.example.com/api/posts`
Tham số (query string)	Lọc, sắp xếp, phân trang	`?limit=10&sort=-publishedAt`
Header	Thông tin bổ sung	`Content-Type: application/json`, `Authorization`
Body	Dữ liệu gửi lên (với POST/PUT/PATCH)	`{"title": "Xin chào"}`

Response (phản hồi)

Thành phần	Ý nghĩa
Mã trạng thái	`2xx` thành công, `3xx` chuyển hướng, `4xx` lỗi phía client, `5xx` lỗi phía server
Header	Loại dữ liệu, cache…
Body	Dữ liệu, thường là JSON

Các mã hay gặp: 200 OK, 201 Created, 400 Bad Request (gửi sai định dạng), 401 Unauthorized (chưa đăng nhập), 403 Forbidden (không đủ quyền), 404 Not Found, 429 Too Many Requests (gọi quá nhiều), 500 Internal Server Error.

JSON là gì?

JSON là định dạng văn bản mô tả dữ liệu theo cặp khóa–giá trị mà cả người lẫn máy đều đọc được:

{
  "title": "CMS là gì?",
  "slug": "cms-la-gi",
  "publishedAt": "2026-11-03T08:00:00.000Z",
  "categories": [{ "name": "So sánh CMS" }]
}

Ví dụ thực tế: gọi API để lấy bài viết

Với một CMS có REST API, bạn có thể lấy danh sách bài viết chỉ bằng một câu lệnh curl. Ví dụ với KDIGI CMS:

curl 'https://cms.example.com/api/posts?where[tenant][equals]=1&sort=-publishedAt&limit=10&depth=1'

Phản hồi là một JSON có dạng danh sách phân trang: docs (mảng bài viết), totalDocs, limit, page, totalPages, hasNextPage… Trong JavaScript:

const res = await fetch(
  'https://cms.example.com/api/posts?' +
    new URLSearchParams({
      'where[tenant][equals]': '1',
      'where[slug][equals]': 'hello-world',
      limit: '1',
      depth: '2',
    }),
)
const { docs } = await res.json()
const post = docs[0]

Đoạn mã trên lấy một bài theo slug. Vì một CMS có thể phục vụ nhiều website, bạn luôn phải lọc theo tenant (website) – đây là quy tắc ghi rõ trong tài liệu API của KDIGI CMS.

Các loại API phổ biến

Loại	Đặc điểm	Khi nào dùng
REST	Mỗi tài nguyên một URL, dùng phương thức HTTP, trả JSON; dễ cache	Mặc định cho website và CMS
GraphQL	Một endpoint, client mô tả chính xác trường cần lấy	Khi cần gom nhiều loại dữ liệu trong một request, tránh thừa dữ liệu
gRPC	Nhị phân, nhanh, định nghĩa bằng Protocol Buffers	Giao tiếp giữa các microservice
SOAP	XML, chuẩn chặt chẽ, có từ lâu	Hệ thống doanh nghiệp/ngân hàng cũ
WebSocket	Kết nối hai chiều liên tục	Chat, dữ liệu thời gian thực
Webhook	Server chủ động gọi tới URL của bạn khi có sự kiện	Thông báo nội dung đã đổi, thanh toán xong

Ngoài ra còn API thư viện/hệ điều hành (ví dụ API của trình duyệt như fetch, localStorage) – cùng là "giao diện để lập trình" nhưng không đi qua mạng.

API key, token và bảo mật cơ bản

API công khai không có nghĩa là ai cũng ghi được dữ liệu. Các lớp bảo vệ thường gặp:

Xác thực (authentication): bạn là ai? Qua cookie đăng nhập, API key hoặc token (JWT, OAuth).
Phân quyền (authorization): bạn được làm gì? Đọc công khai, hay ghi/xóa theo vai trò.
Giới hạn tốc độ (rate limit): chặn gọi quá nhiều.
HTTPS: mã hóa đường truyền. Không bao giờ gửi key qua HTTP thường.
Không lộ bí mật ở frontend: key ghi dữ liệu chỉ để ở server, không nhúng vào JavaScript chạy trên trình duyệt.

Trong KDIGI CMS, request không cookie và không header Authorization chỉ thấy nội dung đã xuất bản (status = published, không nằm trong thùng rác, đã đến giờ đăng). Request có phiên đăng nhập hoặc API key của người dùng sẽ chuyển sang chế độ phạm vi theo từng website và thấy được cả bản nháp và nội dung hẹn giờ của các site mà người đó thuộc về. Hai endpoint ghi công khai là POST /api/comments/create (bình luận luôn ở trạng thái pending chờ duyệt) và POST /api/ratings/submit (đánh giá sao 1–5).

API và CMS headless: mối quan hệ gì?

Trong CMS truyền thống như WordPress, theme của CMS tự lấy dữ liệu và dựng HTML. Trong CMS headless, phần hiển thị bị bỏ đi: CMS chỉ còn trang quản trị và API. Mọi nơi muốn dùng nội dung – website Next.js, Astro, app iOS/Android, màn hình quảng cáo – đều gọi API.

Lợi ích:

Một kho nội dung, nhiều kênh. Viết một lần, hiển thị nhiều nơi.
Frontend tự do. Chọn framework hiệu năng cao, tối ưu Core Web Vitals theo ý bạn.
Tách trách nhiệm. Biên tập viên làm việc trong admin; developer làm việc ở frontend, deploy độc lập.

Đổi lại, bạn phải tự dựng frontend và lo các việc CMS truyền thống làm sẵn: sitemap, thẻ meta, cache. Cách giải quyết trong KDIGI CMS:

Markdown → HTML ngay trong API. Biên tập viên viết Markdown trong contentMd; REST trả HTML đã làm sạch ở khóa content, shortcode đã được mở rộng, thẻ <img> có sẵn width/height khi biết kích thước.
SEO là một phần của dữ liệu. Mỗi tài liệu có nhóm seo (title, description, canonical, Open Graph, breadcrumb…) và seo.jsonLd.raw – cả thẻ <script type="application/ld+json"> sẵn để chèn nguyên văn vào trang.
Webhook revalidate. Khi nội dung đổi, CMS gửi POST https://{domain}/api/cms/revalidate với { "collection", "id", "slug" } để frontend làm mới cache (timeout 5 giây, thử lại tối đa 3 lần).
Locale. Nội dung vi (mặc định) và en, thêm ?locale=en để lấy bản tiếng Anh, có fallback về vi.

Chi tiết xem Headless API của KDIGI CMS và bài CMS là gì?.

REST hay GraphQL trong KDIGI CMS?

KDIGI CMS xây trên Payload nên có cả hai, nhưng theo tài liệu dự án thì REST là hợp đồng chính cho frontend:

	REST	GraphQL
Endpoint	`/api/<collection>`	`POST /api/graphql`
Nội dung	`content` là HTML đã render, shortcode đã mở rộng	Trả raw: `contentMd` là Markdown để bạn tự render; shortcode không được mở rộng
Menu	`items` dựng từ cây theo locale	Trả `tree` thô
Ảnh OG fallback	Có	Chỉ giá trị đã lưu
Production	–	Tắt playground, giới hạn độ phức tạp truy vấn ở 500

Ví dụ GraphQL:

curl https://cms.example.com/api/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ Posts(where: { tenant: { equals: 1 } }, limit: 5) { docs { title slug contentMd } } }"}'

Lời khuyên thực tế: dựng trang bằng REST; dùng GraphQL khi bạn cần các truy vấn gom dữ liệu đặc thù và chấp nhận tự render Markdown.

Dựng một website đọc dữ liệu từ API: các bước

Xác định site. Lấy id của website từ GET /api/sites?where[siteKey][equals]=my-site và cache lại.
Lấy dữ liệu có lọc. Mọi truy vấn kèm where[tenant][equals]=<id>.
Chọn độ sâu. depth=1 đủ để lấy ảnh đại diện và chuyên mục; dùng select để giảm payload cho danh sách.
Render. Hiển thị content (HTML) và đặt <title>, meta, JSON-LD từ trường seo.
Cache + revalidate. Cache trang ở frontend và dựng route /api/cms/revalidate để làm mới khi có webhook.
Áp redirect. Đọc GET /api/redirects?where[isEnabled][equals]=true và xử lý trong middleware.
Giám sát. Kiểm tra GET /api/health – trả {"status":"ok"} mà không truy vấn cơ sở dữ liệu.

Những lỗi thường gặp khi mới làm quen với API

Quên lọc theo site → trả nội dung lẫn của site khác (với CMS đa website).
Gửi cookie/Authorization từ frontend công khai → nhận cả bản nháp hoặc bị giới hạn theo phạm vi site, kết quả khác với người dùng thật.
Render trực tiếp contentMd thay vì content → hiển thị Markdown thô.
Gọi API ở client cho mọi request → chậm và lộ endpoint; hãy gọi ở server/build time và cache.
Bỏ qua mã lỗi → ứng dụng treo thay vì xử lý 404/429/500 một cách mềm mại.

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

API là gì, giải thích đơn giản nhất?

API là cách để hai phần mềm giao tiếp theo quy tắc thống nhất. Phần mềm này gửi yêu cầu, phần mềm kia trả dữ liệu hoặc thực hiện hành động. Ví dụ website của bạn gọi API của CMS để lấy danh sách bài viết mà không cần truy cập trực tiếp cơ sở dữ liệu.

API khác gì so với website?

Website trả về giao diện (HTML, CSS) cho con người đọc. API trả về dữ liệu có cấu trúc (thường là JSON) cho phần mềm khác sử dụng. Một website hiện đại thường gọi API ở phía sau để lấy nội dung rồi tự hiển thị thành giao diện.

REST API là gì?

REST API là kiểu Web API dùng giao thức HTTP: mỗi loại dữ liệu có một URL, bạn dùng GET để đọc, POST để tạo, PUT/PATCH để sửa, DELETE để xóa, và nhận về JSON. REST đơn giản, dễ cache và được hầu hết CMS, kể cả WordPress và KDIGI CMS, hỗ trợ.

Headless CMS có phải là CMS có API không?

Gần đúng, nhưng chính xác hơn: headless CMS chỉ cung cấp quản trị và API, không có lớp hiển thị. Nhiều CMS truyền thống cũng có API; điểm khác là headless coi API là cách phân phối chính, còn frontend là ứng dụng riêng do bạn dựng.

API có miễn phí không?

Tùy nhà cung cấp. API của CMS mã nguồn mở tự host như KDIGI CMS (giấy phép MIT) không tính phí theo lượt gọi; bạn chỉ trả chi phí máy chủ. API của dịch vụ bên thứ ba (bản đồ, thanh toán, AI) thường có hạn mức miễn phí rồi tính phí theo mức dùng.

Làm sao thử API mà không cần viết code?

Dùng curl trong terminal, hoặc công cụ như Postman/Insomnia, hoặc mở thẳng URL của một endpoint GET trên trình duyệt. Với KDIGI CMS, bạn có thể gọi thử endpoint của site opencms rồi so sánh với trang demo trực tuyến.

Nguồn

MDN Web Docs – API (Glossary) và HTTP response status codes
GraphQL Foundation – graphql.org
WordPress – REST API Handbook
Payload – Tài liệu REST API
KDIGI CMS – REST API contract và mã nguồn

Bài viết do Đội ngũ KDIGI biên soạn, cập nhật 03/11/2026. Mọi chi tiết về KDIGI CMS đối chiếu với tài liệu docs/rest-api.md trong kho mã nguồn.