Changelog

Đồng bộ toàn bộ tài liệu với hệ thống thực tế: bổ sung /search, /search/suggest, /trending, /licenses, /tracks/:id/license, /tracks/:id/similar, /tracks/:id/waveform, /tracks/waveforms, /webhooks và /tracks/:id/watermarked vào danh sách endpoint, OpenAPI, Postman và API Playground.

Làm rõ phạm vi xác thực: chỉ /me/usage, /webhooks và /tracks/:id/watermarked cần X-API-Key. Các endpoint đọc kho nhạc là công khai và hiện không tính hạn mức.

Bổ sung các trường metadata vào tài liệu track: like_count, bpm, musical_key, energy, loudness_db, isrc, release_date, license_code, attribution_required, commercial_use_allowed, territory, is_explicit và mảng artists[] (đa nghệ sĩ).

Siết bảo mật đường dẫn media: audio gốc chất lượng cao chỉ quản trị viên truy cập được; API đối tác luôn nhận link nghe thử đã ký, có thời hạn.

Cập nhật tài liệu: bổ sung đầy đủ GET /tracks/:id/audio-url (làm mới link nghe thử) vào bảng endpoint, ví dụ request/response, snippet JavaScript, API Playground và Postman collection.

Thêm GET /tracks/:id/audio-url trả riêng audio_url, cover_url, preview_duration_seconds, media_expires_in và expires_at — dùng thay cho việc lưu cứng link media.

Phát hành đặc tả OpenAPI theo phiên bản tại /api/public/openapi.v1.json (kèm header X-API-Spec-Version); /openapi.json trở thành bí danh của phiên bản mới nhất. Trang tài liệu bổ sung bộ chọn phiên bản.

Thêm GET /readyz (không cần API key, hỗ trợ GET và HEAD) báo trạng thái sẵn sàng nhận traffic kèm timestamp và lý do khi chưa sẵn sàng.

Thêm GET /metrics (không cần API key) xuất số liệu định dạng Prometheus cho hệ thống giám sát của đối tác.

Thêm GET /status (không cần API key) trả chỉ số vận hành, cấu hình rate limit và toàn bộ chính sách đang áp dụng.

Thêm GET /healthz (không cần API key) 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.

Bật Cache-Control và ETag cho mọi response 200; hỗ trợ If-None-Match trả 304. Response lỗi luôn no-store.

Công bố đặc tả OpenAPI 3.1 cho toàn bộ /api/public/* để import thẳng vào Swagger UI, Postman và trình sinh SDK.

Áp dụng X-API-Key kèm rate limit theo phút (429 + Retry-After) và nhật ký request theo từng key cho nhóm endpoint riêng tư của đối tác.

Thêm GET /tracks/by-ids (tối đa 50 ID/lượt) và tài liệu ví dụ request/response cho từng endpoint.

Thêm GET /artists và GET /artists/:id/tracks. Track có thêm artist_id để lọc chính xác.

Chuẩn hóa envelope { data, meta } cho mọi endpoint danh sách; giữ lại header X-Total-Count để tương thích ngược.

Thêm tham số q, title, artist, genre, page, limit cho GET /tracks.