API Explorer trong PolyCMS cho RISE CRM: Sandbox thử nghiệm REST API
API Explorer là plugin dành cho nhà phát triển được tích hợp sẵn trong PolyCMS cho RISE CRM, cung cấp môi trường sandbox trực quan để kiểm thử toàn bộ endpoint của REST API ngay bên trong trang quản trị. Bạn không cần cài đặt phần mềm bên ngoài như Postman hay Insomnia mà vẫn có thể thực thi trực tiếp các lệnh GET, POST, PUT, DELETE trên Posts, Pages, Categories, Tags, Media và sao chép mã nguồn mẫu bằng cURL, PHP, JavaScript hoặc Python.
Điều kiện tiên quyết và cách truy cập
Trước khi gửi yêu cầu thử nghiệm trong sandbox, hãy đảm bảo cả plugin lẫn dịch vụ REST API đều đang bật:
- Đi tới PolyCMS > Plugins và kiểm tra plugin API Explorer đã được kích hoạt (Active).
- Mở PolyCMS > Settings và chuyển sang tab REST API (
#tab-api). - Bật tùy chọn Enable REST API và xác nhận đã khởi tạo khóa API hợp lệ (
pcms_...). - Chọn PolyCMS > API Explorer (
/polycms/api-explorer) trên thanh menu bên trái của RISE CRM. - Chọn tab tài nguyên (Posts, Pages, Categories, Tags hoặc Media), chọn phương thức HTTP và nhấn Send.
Nhân sự cần có quyền Quản trị viên RISE CRM hoặc quyền vai trò polycms_view (cấu hình tại Settings > Access Permission > Roles) để truy cập API Explorer.
Các tài nguyên REST API được hỗ trợ
API Explorer kết nối trực tiếp tới toàn bộ các endpoint REST API v1 dưới tiền tố /cms/api/v1/:
| Tài nguyên | Endpoint | GET | POST | PUT | DELETE | Ghi chú |
|---|---|---|---|---|---|---|
| Posts | /cms/api/v1/posts |
Có | Có | Có | Có | Đầy đủ thao tác CRUD kèm trạng thái, phân loại và ảnh đại diện |
| Pages | /cms/api/v1/pages |
Có | Có | Có | Có | Đầy đủ thao tác CRUD cho trang tĩnh CMS và mẫu template |
| Categories | /cms/api/v1/categories |
Có | Có | Có | Có | Đầy đủ thao tác CRUD bao gồm cấu trúc chuyên mục cha - con |
| Tags | /cms/api/v1/tags |
Có | Có | Có | Có | Đầy đủ thao tác CRUD quản lý hệ thống thẻ tag |
| Media | /cms/api/v1/media |
Có | Có | Không | Có | Lưu trữ qua bảng blog_media, hỗ trợ phân trang, tải lên multipart và xóa liên hoàn |
Các tính năng nổi bật trong Sandbox
Kiểm thử CRUD trực tiếp chỉ bằng một cú nhấp
API Explorer tự động tạo sẵn dữ liệu JSON hợp lệ kèm dấu thời gian (timestamp) cho phần nội dung yêu cầu, giúp bạn kiểm thử thao tác ghi dữ liệu ngay lập tức mà không cần tự gõ JSON thủ công. Sau mỗi yêu cầu POST, PUT hoặc DELETE thành công, danh sách dữ liệu sẽ tự động tải lại để phản ánh chính xác trạng thái mới nhất trong cơ sở dữ liệu.
Hỗ trợ kiểm thử cập nhật PUT thông minh
Khi kiểm thử yêu cầu PUT, API Explorer tự động đọc tiêu đề hiện tại của bản ghi được chọn và gắn thêm hậu tố dấu thời gian. Cơ chế này giúp bạn quan sát rõ kết quả cập nhật mà không gây lỗi trùng lặp slug hay ghi đè nhầm dữ liệu kiểm thử.
Bảng dữ liệu trực quan và trình kiểm tra JSON gốc
Dữ liệu phản hồi được hiển thị đồng thời ở dạng JSON định dạng sạch và bảng dữ liệu có thể sắp xếp với nhãn trạng thái (Published, Draft), liên kết xem nhanh ngoài trang chủ và cửa sổ chi tiết để kiểm tra đầy đủ các trường siêu dữ liệu.
Tự động sinh mã mẫu đa ngôn ngữ
Chuyển tab trong khung mã mẫu để sao chép ngay đoạn mã gọi API đã điền sẵn địa chỉ RISE CRM của bạn cùng header X-PolyCMS-API-Key với 4 ngôn ngữ phổ biến:
- cURL (dòng lệnh và shell script)
- PHP (
curlcho tích hợp backend) - JavaScript (
fetchAPI trên trình duyệt hoặc Node.js) - Python (thư viện
requests)
# Ví dụ lệnh cURL sinh tự động từ API Explorer
curl -X GET \
-H "X-PolyCMS-API-Key: pcms_your_api_key_here" \
-H "Accept: application/json" \
"https://your-rise-crm.com/cms/api/v1/posts"
Kiểm thử tài nguyên Media (blog_media)
Tab Media thao tác trực tiếp trên bảng cơ sở dữ liệu blog_media và thư mục lưu trữ files/polycms/:
- Liệt kê Media (
GET /cms/api/v1/media): Duyệt danh sách tệp đã tải lên với tính năng phân trang, tìm theo tên tệp, lọc theo kiểu MIME, dung lượng và kích thước ảnh. - Tải lên Media (
POST /cms/api/v1/media): Kiểm thử tải tệp bằng biểu mẫumultipart/form-datatích hợp sẵn. Phản hồi trả về giá trịmedia_idmới để bạn gán ngay vào trườngfeature_image_idkhi tạo bài viết hoặc trang tĩnh. - Xóa Media (
DELETE /cms/api/v1/media): Xóa tệp vật lý và ảnh thu nhỏ trongfiles/polycms/, xóa bản ghi trong bảngblog_media, đồng thời tự động gỡ bỏ các tham chiếufeature_imagevàfeature_image_idliên quan trên bài viết và trang tĩnh.
Bảo mật và sự đồng nhất với API thực tế
Mọi yêu cầu gửi từ API Explorer đều xác thực qua header X-PolyCMS-API-Key đang cấu hình và đi qua cùng một chuỗi xử lý REST API phi trạng thái (stateless) như các ứng dụng bên ngoài:
- Loại trừ CSRF chuẩn RISE CRM: PolyCMS đăng ký mẫu
cms/api/v1.*+qua bộ lọcapp_filter_app_csrf_exclude_urisđể các ứng dụng bên ngoài gọi API mượt mà không phụ thuộc cookie phiên làm việc. - Giới hạn tần suất gọi (Rate Limiting): Áp dụng nghiêm ngặt hạn mức đọc và ghi mỗi phút thông qua
Polycms_Rate_Limiter(writable/polycms/rate_limit/). - Làm sạch dữ liệu đầu vào: Toàn bộ nội dung văn bản giàu định dạng được lọc qua thư viện HTMLPurifier nội bộ (
vendor/ezyang/htmlpurifier), còn tệp tải lên đi qua quy trình kiểm duyệt bảo mật tải tệp đầy đủ.
Đối tượng sử dụng phù hợp
- Lập trình viên Headless Frontend kết nối giao diện React, Vue, Next.js hoặc Nuxt với nội dung quản lý trong RISE CRM.
- Kỹ sư tích hợp và ứng dụng di động đồng bộ bài viết, tài liệu sản phẩm hoặc thư viện ảnh sang nền tảng bên thứ ba.
- Nhà phát triển Plugin, Theme và đội QA xác minh cấu trúc payload và phân quyền API trong quá trình phát triển.
Tài liệu liên quan
- Hướng dẫn PolyCMS REST API - Tài liệu đầy đủ về xác thực, danh sách endpoint và cấu hình giới hạn tốc độ.
- Hướng dẫn Thư viện Media - Tìm hiểu cơ chế lưu trữ và quản lý tệp phương tiện.
- Xây dựng Plugin tùy biến cho PolyCMS - Mở rộng tính năng PolyCMS trong RISE CRM.
- Quản lý Plugins trong PolyCMS - Kích hoạt hoặc tạm tắt API Explorer cùng các plugin tích hợp khác.