REST API · v1
Tài liệu API XuniBOX
API chỉ đọc để lấy danh sách nhạc, nghệ sĩ và thể loại từ kho XuniBOX. Mỗi chủ đề dưới đây là một trang riêng, có đường dẫn riêng để bạn chia sẻ cho đội kỹ thuật.
Chính sách phiên bản và thay đổi API
Phần này mô tả cam kết của XuniBOX về việc thay đổi API, để bạn biết cái gì ổn định, cái gì có thể đổi, và bạn cần chuẩn bị gì khi tích hợp lâu dài.
1. Phiên bản đặc tả OpenAPI
| URL | Ý nghĩa | Nên dùng khi |
|---|---|---|
| /api/public/openapi.v1.json | Đặc tả cố định của phiên bản v1, kèm header X-API-Spec-Version. | Tích hợp production, sinh SDK, CI kiểm tra hợp đồng API. |
| /api/public/openapi.json | Bí danh luôn trỏ tới phiên bản mới nhất (hiện là v1). | Thử nhanh, xem tài liệu, demo trong Swagger UI. |
Đường dẫn dữ liệu hiện tại (
/api/public/*) không đổi khi có phiên bản mới. Phiên bản mới sẽ được phát hành dưới tiền tố riêng (ví dụ /api/public/v2/*) kèm đặc tả openapi.v2.json, và v1 vẫn tiếp tục chạy song song.2. Thay đổi nào được coi là an toàn
| Loại thay đổi | Có báo trước? | Ví dụ |
|---|---|---|
| Không phá vỡ (có thể xảy ra bất cứ lúc nào) | Không bắt buộc | Thêm trường mới vào JSON, thêm endpoint mới, thêm tham số truy vấn tùy chọn, thêm giá trị sort mới, cải thiện thông điệp lỗi. |
| Phá vỡ (chỉ xảy ra ở phiên bản mới) | Có, tối thiểu 90 ngày | Xóa hoặc đổi tên trường, đổi kiểu dữ liệu, đổi ý nghĩa mã lỗi, xóa endpoint, bắt buộc thêm tham số. |
| Ngừng hỗ trợ (deprecation) | Có, tối thiểu 180 ngày | Endpoint cũ trả thêm header Deprecation và Sunset trước khi ngừng phục vụ. |
Client của bạn phải bỏ qua trường JSON lạ thay vì báo lỗi. Việc XuniBOX thêm trường mới là thay đổi không phá vỡ và sẽ không được báo trước.
3. Chính sách xác thực và hạn mức
| Quy định | Chi tiết |
|---|---|
| Bắt buộc API key | Mọi endpoint dữ liệu yêu cầu header X-API-Key. Thiếu key trả 401, key sai hoặc bị thu hồi trả 403. |
| Endpoint miễn key | GET /healthz, GET /readyz, GET /status, GET /metrics, GET /openapi.json và GET /openapi.v1.json — không cần key, không tính vào hạn mức. |
| Rate limit | Tính theo từng key trong cửa sổ mỗi phút. Vượt hạn mức trả 429 kèm Retry-After và các header X-RateLimit-*. |
| Ghi nhật ký | Mọi request (kể cả 401/403/429) đều được ghi lại: endpoint, mã trạng thái, IP, user agent, thời gian xử lý — dùng để đối soát khi bạn báo lỗi. |
| Thu hồi key | Admin có thể thu hồi hoặc đổi hạn mức của key bất cứ lúc nào nếu phát hiện lạm dụng; key bị thu hồi trả 403 ngay lập tức. |
4. Chính sách cache
| Nội dung | Cache-Control | Ghi chú |
|---|---|---|
| Response 200 của endpoint dữ liệu | public, max-age=60, s-maxage=300, stale-while-revalidate=600 | Có ETag yếu; gửi lại qua If-None-Match để nhận 304. |
| Đặc tả OpenAPI | public, max-age=300, s-maxage=3600, stale-while-revalidate=86400 | Cache lâu hơn vì hiếm khi đổi trong cùng một phiên bản. |
| Response lỗi 4xx/5xx | no-store | Không bao giờ cache lỗi. |
| URL media (audio_url, cover_url, avatar_url) | Không cache | URL ký hạn 1 giờ — chỉ lưu id, xin URL mới khi cần dùng. |
5. Cam kết vận hành
| Hạng mục | Cam kết |
|---|---|
| Kiểm tra tình trạng | GET /healthz trả api_version, trạng thái hệ thống, thời gian phản hồi và kết nối cơ sở dữ liệu. Trả 503 với status degraded khi backend gặp sự cố. |
| Sẵn sàng nhận traffic | GET /readyz trả ready=true kèm timestamp và thời gian từng check. Khi chưa sẵn sàng trả 503 với reason, reasons và check nào thất bại để đối tác tự điều hướng traffic. |
| Bản tin vận hành | GET /status trả thêm quy mô kho nhạc, hạn mức mặc định 120 request/phút mỗi key, TTL cache và URL ký hạn 1 giờ, giới hạn phân trang cùng danh sách phiên bản đặc tả. |
| CORS | Bật cho mọi origin trên toàn bộ /api/public/*, cho phép header X-API-Key và If-None-Match, expose ETag, Cache-Control và các header X-RateLimit-*. |
| Định dạng lỗi | Luôn là JSON { error, code? } với thông điệp tiếng Việt; cấu trúc này không đổi trong v1. |
| Nội dung nhạc | API chỉ phục vụ đoạn preview đã cắt sẵn (15/30/60 giây), không bao giờ trả file gốc. |
Khi có thay đổi ảnh hưởng tới tích hợp, XuniBOX sẽ cập nhật changelog bên dưới và thông báo tới email đăng ký của key. Nếu bạn gặp sự cố, hãy gửi kèm thời điểm, endpoint và mã trạng thái để admin tra được đúng bản ghi nhật ký.
Sẵn sàng tích hợp?
Gửi thông tin sản phẩm để admin XuniBOX xét duyệt và cấp API key.