Hướng dẫn sử dụng REST API trong PolyCMS

Last updated on Jul 10, 2026 5:02 AM

Tổng quan về REST API

PolyCMS tích hợp sẵn hệ thống REST API mạnh mẽ, cho phép bạn biến hệ thống thành một Headless CMS chuyên nghiệp. Bạn có thể lấy dữ liệu nội dung để hiển thị trên các ứng dụng di động, các trang web bên ngoài hoặc các nền tảng frontend độc lập.

API cung cấp đầy đủ các phương thức CRUD cho Bài viết, Trang tĩnh, Chuyên mục, Thẻ tag và Thư viện phương tiện. Để chạy thử nghiệm các endpoint mà không cần cài đặt phần mềm bên thứ ba, bạn có thể sử dụng màn hình API Explorer tích hợp sẵn.

Trang Demo thực tế: Bạn có thể trải nghiệm công cụ kiểm thử API trực tuyến tại địa chỉ demo chính thức: polycms.polyxgo.com/admin/polycms/api_explorer.

Cơ chế xác thực (Authentication)

Mọi yêu cầu gọi đến API bắt buộc phải được xác thực bằng mã API Key hợp lệ.

Để kích hoạt API và tạo mã khóa mới:

Di chuyển đến mục Blog > Settings.
Tích chọn vào ô Enable REST API.
Tích chọn vào ô Generate New API Key và bấm lưu cài đặt.
Sao chép mã khóa API vừa sinh ra.

Truyền mã khóa API này trong các yêu cầu gọi đi bằng một trong hai cách:

HTTP Header: X-PolyCMS-API-Key: pcms_your_key_here
Tham số URL (Query Parameter): ?api_key=pcms_your_key_here

Giới hạn tần suất gọi (Rate Limiting)

Hệ thống tích hợp cơ chế giới hạn tần suất gọi API để bảo vệ máy chủ khỏi các hành vi spam hay quá tải. Giới hạn được ghi nhận và theo dõi theo địa chỉ IP của ứng dụng gọi đến.

Cấu hình mặc định:

Các lệnh đọc dữ liệu (GET): Tối đa 60 lượt truy cập mỗi phút.
Các lệnh ghi dữ liệu (POST, PUT, DELETE): Tối đa 30 lượt truy cập mỗi phút.

Bạn có thể điều chỉnh các thông số này trong mục Blog > Settings. Hệ thống phản hồi đi kèm các tiêu đề HTTP rate-limiting tiêu chuẩn:

X-RateLimit-Limit
X-RateLimit-Remaining
Retry-After

Nếu vượt quá hạn mức cho phép, API sẽ trả về mã lỗi HTTP 429 Too Many Requests.

Danh sách các Endpoints

Tất cả các đường dẫn API đều bắt đầu bằng tiền tố /cms/api/v1/.

Bài viết (Posts)

Lấy danh sách bài viết:

GET /cms/api/v1/posts

Các tham số lọc tùy chọn:

page (mặc định: 1)
per_page (mặc định: 10, tối đa: 100)
status (ví dụ: published, draft)
category_id
author_id
search
sort_by (mặc định: created_at)
sort_order (mặc định: DESC)

Lấy chi tiết một bài viết:

GET /cms/api/v1/posts/{id}

Tạo mới bài viết:

POST /cms/api/v1/posts

Cấu trúc body gửi lên dạng JSON:

{
  "title": "Tiêu đề bài viết mới",
  "content": "Nội dung bài viết...",
  "status": "published",
  "category_ids": [1, 2]
}

Cập nhật bài viết:

PUT /cms/api/v1/posts/{id}

Xóa bài viết:

DELETE /cms/api/v1/posts/{id}

Trang tĩnh (Pages)

Lấy danh sách trang tĩnh:

GET /cms/api/v1/pages

Lấy chi tiết một trang tĩnh:

GET /cms/api/v1/pages/{id}

Tạo mới / Cập nhật / Xóa trang tĩnh:

Các endpoint tương ứng: POST /cms/api/v1/pages, PUT /cms/api/v1/pages/{id}, DELETE /cms/api/v1/pages/{id}.

Chuyên mục (Categories)

Lấy cấu trúc chuyên mục (trả về định dạng sơ đồ cây phân cấp):

GET /cms/api/v1/categories

Các endpoint CRUD: POST /cms/api/v1/categories, PUT /cms/api/v1/categories/{id}, DELETE /cms/api/v1/categories/{id}.

Thẻ tag (Tags)

Lấy danh sách thẻ tag:

GET /cms/api/v1/tags

Các endpoint CRUD: POST /cms/api/v1/tags, PUT /cms/api/v1/tags/{id}, DELETE /cms/api/v1/tags/{id}.

Thư viện phương tiện (Media)

Duyệt tìm tệp phương tiện (Lưu cơ sở dữ liệu, hỗ trợ phân trang):

GET /cms/api/v1/media

Các tham số lọc tùy chọn:

page (mặc định: 1)
per_page (mặc định: 20, tối đa: 100)
search — Tìm kiếm theo tên tệp tin, alt_text, hoặc tiêu đề
mime — Lọc theo định dạng MIME (ví dụ: image)

Tải lên tệp phương tiện:

POST /cms/api/v1/media

Tải tệp tin lên bằng định dạng multipart/form-data với tên trường dữ liệu là file. API áp dụng **cơ chế bảo mật nghiêm ngặt 6 lớp** bao gồm: kiểm tra đuôi tệp tin cho phép, xác thực MIME-type thực tế, kiểm tra magic bytes đầu tệp, quét phát hiện mã độc nhúng, chặn tệp đuôi kép và tái xử lý hình ảnh qua thư viện GD để dọn sạch payloads.

Sau khi tải lên thành công, kết quả trả về sẽ cung cấp mã media_id để bạn liên kết làm ảnh đại diện cho bài viết hay trang tĩnh qua thuộc tính feature_image_id.

Xóa tệp phương tiện:

DELETE /cms/api/v1/media/{path}

Hệ thống tự động thực hiện **quy trình dọn dẹp 3 lớp** chéo để xóa file vật lý trên đĩa, xóa dòng bản ghi trong database blog_media và tự động gỡ liên kết ảnh đại diện trên các bài viết hay trang tĩnh đang sử dụng tệp tin này.

Định dạng dữ liệu phản hồi (Response Format)

Mọi kết quả API thành công đều trả về cấu trúc dữ liệu JSON đồng bộ:

{
  "success": true,
  "message": "Danh sách bài viết đã được truy xuất",
  "data": [
    {
      "id": 1,
      "title": "Chào thế giới",
      ...
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "per_page": 10,
    "pages": 1
  }
}

Các trường hợp lỗi sẽ trả về thuộc tính success: false kèm thông tin mô tả chi tiết lỗi và mã lỗi HTTP tương ứng.

Chính sách Bảo mật và Cô lập Dữ liệu

Giới hạn phạm vi dữ liệu — Chỉ tác động trên các bảng CMS

Hệ thống REST API hoạt động **duy nhất** trên các bảng dữ liệu của phân hệ PolyCMS. Hệ thống **hoàn toàn không có quyền truy cập** đến các dữ liệu cốt lõi của Perfex CRM (như hồ sơ khách hàng, hóa đơn doanh nghiệp, thông tin dự án, danh sách lead hay mật khẩu nhân viên).

API chỉ tương tác với các bảng dữ liệu riêng biệt sau:

blog_posts / blog_post_meta / blog_post_tags
blog_pages / blog_page_meta
blog_categories
blog_tags
blog_media

Tương tác duy nhất với dữ liệu CRM là đọc thông tin Họ tên hiển thị của nhân viên từ bảng staff để gán làm tên tác giả bài viết. Không một thông tin nhạy cảm nào của CRM bị lộ hay cho phép chỉnh sửa qua API.

Bảo vệ chống tấn công SQL Injection

Không sử dụng câu lệnh SQL thuần: Mọi truy vấn database được viết bằng trình dựng CodeIgniter Active Record / Query Builder hỗ trợ tự động escape dữ liệu an toàn.
Ràng buộc tham số chặt chẽ: Các giá trị bộ lọc đầu vào đều đi qua bộ lọc escape mặc định của CodeIgniter.
Chuẩn hóa kiểu dữ liệu: Các tham số dạng số (như ID bản ghi, trang số...) đều được ép kiểu sang (int) trước khi thực thi.

Chốt chặn an toàn XSS và Content Injection

Sử dụng bộ lọc HTMLPurifier: Mọi nội dung bài viết gửi lên qua API được xử lý qua hàm polycms_purify_content() tích hợp sẵn thư viện HTMLPurifier, hỗ trợ bóc tách các thẻ <script> và loại bỏ các sự kiện script nội dòng (như onclick, onerror...).
Loại bỏ thẻ HTML ở các trường text: Các trường thông tin dạng text thông thường (như tiêu đề, slug, trạng thái...) đều đi qua hàm strip_tags() để loại bỏ hoàn toàn các thẻ HTML.

Tài liệu hướng dẫn liên quan

Màn hình API Explorer — Môi trường thử nghiệm API trực tiếp trong trang quản trị.
Tự viết một Plugin tùy biến — Hướng dẫn lập trình mở rộng tính năng API.
Tài liệu tham khảo Hooks & Filters — Hướng dẫn đăng ký action và filter can thiệp vào luồng xử lý của API.