HeadRandom
Back to Main Site

PolyCMS REST API: Hướng dẫn lập trình viên toàn diện với cơ sở dữ liệu Media

Last updated on Sep 6, 2026 9:26 PM 9:26 PM 330.31 ms

PolyCMS REST API cho phép các ứng dụng bên ngoài tương tác lập trình với toàn bộ dữ liệu nội dung trong CMS của bạn. Dù bạn đang phát triển ứng dụng di động, giao diện Headless hiện đại với React/Vue/Astro hay tích hợp dữ liệu với các dịch vụ bên thứ ba, REST API đều cung cấp quyền truy cập bảo mật, chuẩn hóa vào kho nội dung.

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

Mọi yêu cầu gọi đến API đều cần cung cấp API Key hợp lệ. Bạn có thể truyền khóa thông qua tiêu đề HTTP X-PolyCMS-API-Key (khuyến nghị) hoặc tham số truy vấn URL ?api_key=:

curl -X GET \
  -H "X-PolyCMS-API-Key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  "https://your-site.com/cms/api/v1/posts"

Danh sách các Điểm cuối (Available Endpoints)

Hệ thống cung cấp đầy đủ các thao tác đọc và ghi dữ liệu trên toàn bộ tài nguyên:

Tài nguyên (Resource) GET (Danh sách/Chi tiết) POST (Tạo mới) PUT (Cập nhật) DELETE (Xóa)
Posts (Bài viết) Có Có Có Có
Pages (Trang tĩnh) Có Có Có Có
Categories (Danh mục) Có Có Có Có
Tags (Thẻ) Có Có Có Có
Media (Tệp tin đa phương tiện) Có Có - Có

Tải lên Media & Theo dõi trong Cơ sở dữ liệu

Tải lên tệp tin hình ảnh qua endpoint POST /cms/api/v1/media sử dụng định dạng multipart/form-data với trường tên file. API thực thi nghiêm ngặt 6 lớp bảo mật chuyên sâu:

  1. Danh sách trắng phần mở rộng (extension whitelist).
  2. Kiểm tra định dạng MIME chuẩn xác.
  3. Xác minh chữ ký nhị phân (magic bytes).
  4. Quét mã độc tiềm ẩn trong tệp tin.
  5. Chặn hoàn toàn kỹ thuật đặt tên tệp hai đuôi (double-extension).
  6. Tái xử lý hình ảnh qua thư viện GD để loại bỏ mã khai thác nhúng ngầm (payload stripping).

Theo dõi chi tiết qua bảng blog_media

Mọi tệp media tải lên thành công đều được lưu vết chi tiết trong bảng cơ sở dữ liệu blog_media với các trường thông tin:

  • filename: Tên tệp tin gốc.
  • path: Đường dẫn tương đối trên đĩa lưu trữ (ví dụ: 2026/05/17/my-image.jpg).
  • url: Đường dẫn URL đầy đủ để hiển thị trực tiếp trên frontend.
  • alt_text: Văn bản thay thế tối ưu hóa SEO.
  • title: Tiêu đề tệp tin.
  • caption: Chú thích chi tiết của hình ảnh.
  • mime_type: Định dạng MIME được hệ thống nhận diện (ví dụ: image/jpeg).
  • file_size: Kích thước tệp tính theo bytes.
  • width / height: Độ phân giải chiều rộng và chiều cao tính theo pixel.
  • author_id: ID nhân viên đã thực hiện tải lên tệp tin.

Khi tải lên thành công, API trả về ngay media_id để gán trực tiếp vào trường feature_image_id của Bài viết hoặc Trang.

curl -X POST \
  -H "X-PolyCMS-API-Key: YOUR_API_KEY" \
  -F "file=@photo.jpg" \
  "https://your-site.com/cms/api/v1/media"

Truy vấn Danh sách Media có Phân trang

Endpoint GET /cms/api/v1/media truy vấn trực tiếp từ cơ sở dữ liệu thay vì quét tệp tin trên ổ đĩa, đảm bảo tốc độ phản hồi tính bằng mili-giây:

  • page: Số trang cần lấy (Mặc định: 1).
  • per_page: Số lượng mục trên mỗi trang (Mặc định: 20, tối đa 100).
  • search: Tìm kiếm nhanh theo tên tệp, văn bản alt hoặc tiêu đề.
  • mime: Lọc theo tiền tố định dạng MIME (ví dụ: image).

Cơ chế Xóa Media dạng Thác đổ (Delete Cascade)

Khi xóa một tệp tin qua DELETE /cms/api/v1/media/{path}, PolyCMS tự động kích hoạt quy trình dọn dẹp 3 tầng:

  1. Xóa tệp vật lý: Xóa vĩnh viễn tệp tin gốc và ảnh thumbnail tương ứng khỏi ổ đĩa máy chủ.
  2. Xóa bản ghi dữ liệu: Xóa dòng dữ liệu tương ứng trong bảng blog_media.
  3. Dọn sạch tham chiếu (Cascade): Tự động xóa liên kết ảnh đại diện trong các bài viết hoặc trang đang sử dụng tệp tin này, tránh tình trạng ảnh lỗi (broken image) trên website.

Quan hệ Ảnh đại diện (Feature Image Relationship)

Cột feature_image_id trong bảng Posts và Pages tạo liên kết trực tiếp với bảng blog_media. Đồng thời, chuỗi đường dẫn tệp vẫn được duy trì để phục vụ việc hiển thị trang cực nhanh mà không cần thực hiện các câu lệnh truy vấn JOIN phức tạp.

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

API áp dụng chính sách giới hạn tần suất truy cập có thể cấu hình linh hoạt (mặc định: 60 lượt đọc / 30 lượt ghi mỗi phút). Thông tin giới hạn luôn được phản hồi rõ ràng trong tiêu đề HTTP:

  • X-RateLimit-Limit: Tổng số yêu cầu được phép trong khung thời gian.
  • X-RateLimit-Remaining: Số lượng yêu cầu còn lại.
  • Retry-After: Thời gian chờ (giây) trước khi được thực hiện yêu cầu tiếp theo nếu vượt ngưỡng.

Hướng dẫn Bắt đầu Nhanh

  1. Truy cập trang quản trị: Blog > Settings > REST API.
  2. Bật công tắc kích hoạt REST API.
  3. Nhấp tạo mới API Key và sao chép mã khóa an toàn.
  4. Cấu hình giới hạn tần suất truy cập phù hợp với quy mô tải của máy chủ.
  5. Sử dụng công cụ API Explorer tích hợp sẵn để kiểm tra trực quan các endpoint.

Tham khảo thêm các hướng dẫn liên quan: