Hướng dẫn REST API PolyCMS Core: Tài liệu lập trình viên toàn diện

Last updated on Jul 21, 2026 7:51 AM

Bài viết này cung cấp tài liệu chi tiết về danh sách các API endpoint, tham số request, định dạng dữ liệu phản hồi JSON và hướng dẫn kết nối tích hợp cho hệ thống REST API của PolyCMS Core.

Kiến trúc API & Cơ chế xác thực (Authentication)

PolyCMS Core cung cấp các endpoint RESTful API dưới tiền tố /api/v1. Tất cả các request yêu cầu bảo mật đều phải được xác thực thông qua Bearer Token được quản lý bởi thư viện Laravel Sanctum.

Để thực hiện xác thực và gọi API:

Đăng nhập vào trang quản trị PolyCMS Admin Panel.
Truy cập vào trang cá nhân của bạn, chọn API Tokens (hoặc truy cập Cài đặt > API Tokens).
Tạo một token mới, sao chép khóa API dạng chuỗi text thô và lưu trữ an toàn.
Truyền khóa token này vào HTTP Header Authorization cho mỗi request gửi lên:

Authorization: Bearer YOUR_SANCTUM_TOKEN_HERE
Accept: application/json
Content-Type: application/json

Danh sách Endpoint & Chi tiết API Reference

1. Quản lý Bài viết & Trang tĩnh (Posts & Pages)

Lấy danh sách bài viết: GET /api/v1/posts
- Tham số truy vấn (Query Parameters):
  - page (integer): Số trang hiện tại (mặc định là 1).
  - per_page (integer): Số lượng bài viết trên mỗi trang (mặc định là 15, tối đa 100).
  - status (string): Lọc trạng thái (published hoặc draft).
  - category_id (integer): Lọc theo ID danh mục.
  - search (string): Từ khóa tìm kiếm trong tiêu đề hoặc nội dung.
  - sort_by (string): Cột sắp xếp (created_at, views, order).
- Dữ liệu phản hồi mẫu (Response Payload):
```
{
  "data": [
    {
      "id": 12,
      "title": "Getting Started with PolyCMS",
      "slug": "getting-started-with-polycms",
      "type": "post",
      "status": "published",
      "locale": "en",
      "content_html": "<p>Welcome to PolyCMS...</p>"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 15,
    "total": 75
  }
}
```
Lấy chi tiết một bài viết: GET /api/v1/posts/{id_hoac_slug}
Tạo mới bài viết: POST /api/v1/posts (Yêu cầu Xác thực)
- Tham số trong Request Body:
  - title (string, bắt buộc): Tiêu đề bài viết.
  - slug (string, bắt buộc): Slug thân thiện với URL và duy nhất.
  - content_raw (array, tùy chọn): Cấu trúc JSON blocks của trình soạn thảo TipTap.
  - content_html (string, tùy chọn): HTML thô của bài viết (nếu không truyền content_raw).
  - status (string, tùy chọn): draft hoặc published (mặc định là draft).
  - locale (string, tùy chọn): Mã ngôn ngữ (mặc định là en).
  - translation_group_id (string, tùy chọn): Mã UUID để liên kết các ngôn ngữ dịch.
Cập nhật bài viết: PUT /api/v1/posts/{id} (Yêu cầu Xác thực)
Xóa bài viết: DELETE /api/v1/posts/{id} (Yêu cầu Xác thực)

2. Sản phẩm E-Commerce (Products)

Lấy danh sách sản phẩm: GET /api/v1/products
- Tham số lọc: page, per_page, search, category_id, brand_id.
Lấy chi tiết sản phẩm: GET /api/v1/products/{id}
Thao tác CRUD Sản phẩm: Hỗ trợ đầy đủ các phương thức POST / PUT / DELETE trên endpoint /api/v1/products (Yêu cầu Xác thực).

3. Danh mục & Thẻ Phân loại (Categories & Tags)

Lấy cây danh mục: GET /api/v1/categories (Trả về danh sách dạng cây phân cấp).

Tạo mới danh mục: POST /api/v1/categories (Yêu cầu Xác thực)

Request Body:

{
  "name": "Developer Guide",
  "slug": "developer-guide",
  "parent_id": null
}

Cập nhật / Xóa danh mục: Các phương thức PUT / DELETE tương ứng tại /api/v1/categories/{id} (Yêu cầu Xác thực).

4. Thư viện tệp tin Media

Lấy danh sách media: GET /api/v1/media (Yêu cầu Xác thực)
- Trả về danh sách tệp tin tải lên có phân trang, lọc theo định dạng MIME.
Tải lên tệp tin Media: POST /api/v1/media/upload (Yêu cầu Xác thực)
- Content-Type: multipart/form-data
- Payload: Truyền tệp tin qua khóa file.
- Quy trình kiểm tra bảo mật: Hệ thống áp dụng quy trình kiểm tra 6 lớp nghiêm ngặt (xác thực định dạng MIME thực tế, chặn extension kép, tải lại và tối ưu qua thư viện GD để loại bỏ mã độc ẩn trong ảnh, và quét virus).
Xóa tệp tin Media: DELETE /api/v1/media/{id} (Yêu cầu Xác thực)
- Tự động xóa file vật lý trên đĩa cứng, dọn dẹp bản ghi DB và gỡ liên kết ảnh đại diện (feature_image) của các bài viết liên quan.

5. Quản lý Cache hệ thống

Xem trạng thái cache: GET /api/v1/system/cache/status (Yêu cầu Xác thực)
Xóa cache hệ thống: POST /api/v1/system/cache/clear (Yêu cầu Xác thực)
- Xóa toàn bộ cache ứng dụng, cache biên dịch Blade views, cache config và cache truy vấn CSDL.

Ví dụ mã nguồn kết nối tích hợp

JavaScript (Sử dụng Fetch API)

const token = 'YOUR_SANCTUM_TOKEN';
const baseUrl = 'https://polycms.org/api/v1';

async function fetchPosts() {
  const response = await fetch(`${baseUrl}/posts?status=published`, {
    method: 'GET',
    headers: {
      'Accept': 'application/json',
      'Authorization': `Bearer ${token}`
    }
  });
  
  if (response.ok) {
    const payload = await response.json();
    console.log(payload.data);
  }
}

Python (Sử dụng Requests)

import requests

token = "YOUR_SANCTUM_TOKEN"
headers = {
    "Accept": "application/json",
    "Authorization": f"Bearer {token}"
}

response = requests.get("https://polycms.org/api/v1/posts", headers=headers)
if response.status_code == 200:
    posts = response.json().get("data", [])
    print(f"Lấy thành công {len(posts)} bài viết.")