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.

Bắt đầu nhanh Xem endpoints Tra cứu yêu cầu

Danh sách endpoint

Method & path	Trả về
GET /healthz	Trạng thái API, phiên bản, thời gian phản hồi và kết nối DB. Không cần key.
GET /readyz	Readiness: hệ thống đã sẵn sàng nhận traffic chưa, kèm timestamp, từng check và lý do lỗi. Không cần key.
GET /status	Chỉ số vận hành (quy mô kho nhạc, DB) + cấu hình rate limit và chính sách hiện hành. Không cần key.
GET /metrics	Số liệu định dạng Prometheus (text/plain) để hệ thống giám sát scrape. Không cần key.
GET /tracks	Danh sách bài hát có lọc, tìm kiếm, sắp xếp, phân trang.
GET /tracks/:id	Một bài hát. Không tăng play_count.
GET /tracks/:id/audio-url	Link nghe thử đã ký còn hạn cho một bài — gọi ngay trước khi phát.
GET /tracks/by-ids	Tối đa 50 bài trong một lượt, giữ thứ tự ID đầu vào.
GET /genres	Danh sách thể loại đang được dùng, A→Z.
GET /artists	Danh sách nghệ sĩ kèm số bài nhạc.
GET /artists/:id/tracks	Thông tin nghệ sĩ + danh sách bài của họ.

GET/healthz

Kiểm tra nhanh khi tích hợp. Không cần API key, không tốn hạn mức rate limit.

GET/readyz

Readiness probe: trả 200 khi sẵn sàng nhận traffic, 503 kèm reason khi chưa. Hỗ trợ cả HEAD, không cần API key.

GET/metrics

Số liệu theo chuẩn Prometheus text exposition 0.0.4: xunibox_up, xunibox_database_up, xunibox_database_response_seconds, xunibox_tracks_total, xunibox_artists_total, xunibox_track_plays_total, xunibox_rate_limit_requests_per_minute, xunibox_scrape_duration_seconds. Không cần API key, không tốn hạn mức, không cache.

GET/status

Bản tin vận hành chi tiết: trạng thái hệ thống, số bài nhạc/nghệ sĩ, hạn mức mặc định của API key, chính sách cache, phân trang, CORS và danh sách phiên bản đặc tả. Không cần API key.

GET/tracks

Danh sách bài hát, hỗ trợ tìm kiếm, lọc, sắp xếp và phân trang.

titlestringTìm một phần tên bài hát, tối đa 160 ký tự.

genrestringTìm một phần thể loại, tối đa 80 ký tự.

artiststringTìm một phần tên nghệ sĩ, tối đa 120 ký tự.

artist_iduuidLọc chính xác theo ID nghệ sĩ lấy từ /artists.

qstringTìm đồng thời trong tên bài hát, nghệ sĩ và thể loại, tối đa 100 ký tự.

sortenumnewest (mặc định), oldest, popular, title_asc, title_desc.

pageintegerTrang cần lấy, từ 1 đến 5000, mặc định 1.

limitintegerSố bản ghi mỗi trang, mặc định 20, tối đa 100.

GET/tracks/:id

Một bài hát theo UUID. 400 nếu ID sai định dạng, 404 nếu không tồn tại.

GET/tracks/:id/audio-url

Làm mới link nghe thử đã ký cho một bài. Trả audio_url, cover_url, preview_duration_seconds, media_expires_in (giây) và expires_at (ISO 8601). Luôn Cache-Control: no-store. 400 nếu ID sai định dạng, 404 nếu bài không tồn tại hoặc chưa có đoạn nghe thử.

GET/tracks/by-ids

Lấy nhiều bài cùng lúc, dùng khi khôi phục playlist đã lưu.

idsstringDanh sách UUID cách nhau bởi dấu phẩy, tối đa 50. ID trùng được gộp, ID không tồn tại bị bỏ qua.

GET/genres

Các thể loại đang thực sự có bài nhạc, sắp xếp A→Z.

pageintegerTrang cần lấy, mặc định 1.

limitintegerSố thể loại mỗi trang, mặc định 20, tối đa 100.

GET/artists

Nghệ sĩ kèm tiểu sử, ảnh đại diện và tổng số bài nhạc.

qstringTìm theo tên nghệ sĩ, tối đa 100 ký tự.

sortenumname_asc (mặc định), name_desc, newest, oldest.

pageintegerTrang cần lấy, mặc định 1.

limitintegerSố nghệ sĩ mỗi trang, mặc định 20, tối đa 100.

GET/artists/:id/tracks

Thông tin nghệ sĩ và danh sách bài nhạc của họ. 404 nếu nghệ sĩ không tồn tại.

sortenumnewest (mặc định), oldest, popular, title_asc, title_desc.

pageintegerTrang cần lấy, mặc định 1.

limitintegerSố bài mỗi trang, mặc định 20, tối đa 100.

Quy ước chung Xu hướng vận hành

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.

Xin quyền tích hợp