Việc tích hợp và sử dụng hệ thống REST API của PolyCMS cho phép các nhà phát triển sử dụng nền tảng này như một headless CMS độc lập. Bằng cách cung cấp đầy đủ các phương thức CRUD để truy xuất và quản trị dữ liệu bài viết, trang tĩnh, danh mục, thẻ tag và thư viện media, API giúp việc xây dựng các ứng dụng di động hoặc các giao diện tùy biến bên ngoài trở nên đơn giản và bảo mật.
Tổng quan về REST API
PolyCMS tích hợp sẵn hệ thống REST API mạnh mẽ để phục vụ các kiến trúc headless CMS. Bạn có thể dễ dàng lấy dữ liệu nội dung để hiển thị trên các ứng dụng di động, các trang web vệ tinh hoặc các ứng dụng frontend sử dụng framework độc lập.
API hỗ trợ đầy đủ các thao tác CRUD (Create, Read, Update, Delete) cho các đối tượng Posts, Pages, Categories, Tags và Media. Để thử nghiệm trực tiếp các endpoint này mà không cần cài đặt thêm bất kỳ công cụ bên thứ ba nào, bạn có thể sử dụng công cụ API Explorer được tích hợp sẵn trong trang quản trị.
Cơ chế xác thực (Authentication)
Tất cả các yêu cầu gửi đến API đều yêu cầu phải được xác thực thông qua API Key.
Để kích hoạt API và tạo khóa xác thực:
- Truy cập vào Blog > Cài đặt.
- Đánh dấu vào ô Kích hoạt REST API.
- Đánh dấu vào ô Tạo mới API Key và lưu lại.
- Sao chép khóa API được tạo ra.
Bạn có thể truyền khóa API này vào request theo một trong hai cách:
- HTTP Header:
X-PolyCMS-API-Key: pcms_your_key_here - Tham số Query:
?api_key=pcms_your_key_here
Giới hạn tần suất yêu cầu (Rate Limiting)
Hệ thống tích hợp sẵn cơ chế giới hạn tần suất để bảo vệ máy chủ khỏi các cuộc tấn công từ chối dịch vụ. Giới hạn được theo dõi và áp dụng dựa trên địa chỉ IP của client gửi yêu cầu.
Cấu hình mặc định:
- Thao tác đọc dữ liệu (GET): Tối đa 60 yêu cầu mỗi phút.
- Thao tác ghi dữ liệu (POST, PUT, DELETE): Tối đa 30 yêu cầu mỗi phút.
Bạn có thể điều chỉnh các thông số này trong phần cài đặt của Blog. Khi vượt quá giới hạn, API sẽ trả về mã lỗi HTTP 429 Too Many Requests kèm theo các header phản hồi tiêu chuẩn:
X-RateLimit-LimitX-RateLimit-RemainingRetry-After
Các Endpoint chính của hệ thống
Tất cả các endpoint API của hệ thống đều có tiền tố chung là /cms/api/v1/.
1. Bài viết (Posts)
- Lấy danh sách bài viết:
GET /cms/api/v1/postsHỗ trợ các tham số lọc:page,per_page,status(draft/published),category_id,author_id,search,sort_by,sort_order. - 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ậ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}
2. Trang tĩnh (Pages)
- Lấy danh sách trang tĩnh:
GET /cms/api/v1/pages - Lấy chi tiết trang:
GET /cms/api/v1/pages/{id} - Hỗ trợ đầy đủ các thao tác POST, PUT, DELETE tương tự bài viết.
3. Danh mục & Thẻ (Categories & Tags)
- Lấy cây danh mục:
GET /cms/api/v1/categories(trả về cấu trúc cây phân cấp). - Quản lý danh mục/thẻ: Hỗ trợ đầy đủ các thao tác thêm, sửa, xóa qua POST, PUT, DELETE.
4. Thư viện Media
- Lấy danh sách media:
GET /cms/api/v1/media(Hỗ trợ phân trang, tìm kiếm và lọc theo loại tệp tin MIME). - Tải lên media:
POST /cms/api/v1/mediaHỗ trợ tải lên qua định dạngmultipart/form-data. Hệ thống áp dụng quy trình kiểm tra bảo mật 6 lớp (kiểm tra phần mở rộng, xác thực MIME, magic bytes, quét mã độc, chặn phần mở rộng kép và xử lý lại ảnh qua thư viện GD để loại bỏ mã độc nhúng). - Xóa media:
DELETE /cms/api/v1/media/{path}Tự động thực hiện dọn dẹp liên kết: xóa tệp tin vật lý trên đĩa, xóa bản ghi trong DB và gỡ bỏ liên kết ảnh đại diện (feature_image) của các bài viết đang tham chiếu đến media này.
Kiến trúc cơ sở dữ liệu và bảo mật
Từ phiên bản v1.1.0, tất cả các tệp tin tải lên được quản lý tập trung trong bảng dữ liệu blog_media. Bài viết và trang tĩnh liên kết với ảnh đại diện thông qua khóa ngoại feature_image_id.
Cơ chế cô lập dữ liệu
REST API được thiết kế để hoạt động độc lập và chỉ có quyền truy cập vào các bảng dữ liệu chuyên biệt của CMS (như blog_posts, blog_categories, blog_media, v.v.). API hoàn toàn không có quyền truy cập hay can thiệp vào cơ sở dữ liệu cốt lõi của CRM (như thông tin khách hàng, hóa đơn, dự án, mật khẩu nhân viên). Điều này đảm bảo an toàn thông tin tuyệt đối cho doanh nghiệp khi cung cấp API ra bên ngoài.