Tổng quan kiến trúc & REST API

Đặc tả kỹ thuật OpenAPI 3.1, URL cơ sở và các nguyên tắc kiến trúc cốt lõi của SmallPict API.

SmallPict REST API là một dịch vụ web hiệu năng cao tuân thủ hoàn toàn tiêu chuẩn OpenAPI 3.1, cho phép các lập trình viên kết nối trực tiếp với hệ thống tối ưu hóa hình ảnh, chuyển đổi định dạng và phân phối biên qua CDN.

Các địa chỉ URL cơ sở (Base URLs)

Môi trường	Địa chỉ URL	Mô tả môi trường
Môi trường sản xuất (Production)	`https://api.smallpict.app/v1`	Cổng API chính thức với định tuyến Anycast toàn cầu
Máy chủ giả lập cục bộ (Mock)	`http://localhost:8080/v1`	Môi trường sandbox cho kiểm thử đơn vị và phát triển

Các điểm cuối API cốt lõi

Tất cả các điểm cuối yêu cầu xác thực bằng chữ ký HMAC-SHA256 trong tiêu đề HTTP (xem Hướng dẫn xác thực).

1. Tối ưu hóa và chuyển đổi định dạng ảnh

Điểm cuối: POST /v1/optimize (Tên bí danh: POST /v1/convert)
Mô tả: Gửi siêu dữ liệu hoặc tệp ảnh nhị phân để nén và chuyển đổi định dạng (AVIF, WebP, JPEG, PNG).

2. Truy vấn tiến trình công việc bất đồng bộ

Điểm cuối: GET /v1/optimize/status?job_id={job_id}
Mô tả: Kiểm tra tiến độ xử lý của các tệp ảnh lớn, tỷ lệ dung lượng tiết kiệm và URL tải về từ CDN.

3. Hạn ngạch tài khoản & Thống kê lưu lượng

Điểm cuối: GET /v1/quota
Mô tả: Lấy thông số số byte đã xử lý theo thời gian thực, giới hạn gói tháng và lưu lượng băng thông CDN đã dùng.

4. Xóa bộ nhớ đệm Edge CDN

Điểm cuối: POST /v1/purge
Mô tả: Vô hiệu hóa và xóa bộ nhớ đệm của các tài nguyên ảnh cụ thể trên hơn 300 điểm hiện diện SmallPict Edge.

Tiêu chuẩn định dạng yêu cầu & phản hồi

Tất cả dữ liệu gửi đi (payload) mặc định sử dụng định dạng application/json (hoặc multipart/form-data khi tải trực tiếp tệp nhị phân).
Tất cả dữ liệu phản hồi trả về JSON có cấu trúc, với các mốc thời gian tuân thủ tiêu chuẩn RFC3339.
Mọi yêu cầu làm thay đổi trạng thái (POST, DELETE, PATCH) đều hỗ trợ tiêu đề Idempotency-Key (UUID v4) để đảm bảo không bị trừ phí trùng lặp khi mạng thử lại.