Playlist API Endpoints
Relevant source files
The following files were used as context for generating this wiki page:
The Playlist API Endpoints provide the interface for managing music collections within the HX-Music system. These endpoints allow users to create, modify, delete, and organize playlists, as well as manage the individual songs contained within them. The API follows a client-server architecture where the server manages persistence via a database and the client interacts through asynchronous HTTP requests.
The system distinguishes between several playlist types: global playlists, user-created playlists, and user-saved (bookmarked) playlists. Access to these endpoints is governed by a permission-based system including Administrator, RegularUser, and ReadOnlyUser.
Sources: HX-Music-Server/doc/api.md:1-10, HX-Music-Server/include/api/PlaylistApi.hpp:41-43
API Architecture and Data Flow
The Playlist API utilizes Data Transfer Objects (DTOs) categorized as Value Objects (VO) for client-server communication and Domain Objects (DO) for database persistence. The server implementation leverages asynchronous C++ coroutines to handle requests efficiently.
Data Structures
| Class/Struct | Purpose | Key Fields |
|---|---|---|
PlaylistDO | Database Persistence | id, name, description, songIdList |
PlaylistVO | Full Data Transfer | id, name, description, songList (MusicVO) |
PlaylistInfoVO | Metadata Summary | id, name, description, cnt (Song count) |
IdListVO | Batch Sorting | idList (Vector of IDs) |
Sources: include/pojo/do/PlaylistDO.hpp:25-30, include/pojo/vo/PlaylistVO.hpp:26-31, include/pojo/vo/PlaylistInfoVO.hpp:31-36
Request Lifecycle
The following sequence diagram illustrates the flow of a playlist creation request from the client to the server and the subsequent database updates.
The server performs three primary actions during creation: persisting the new playlist record, retrieving the user's current creation list, and appending the new ID to that list.
Sources: HX-Music-Server/include/api/PlaylistApi.hpp:46-67
Endpoint Reference
Management Endpoints
These endpoints handle the lifecycle of the playlist entity itself.
- Create Playlist (
POST /playlist/make): Creates a new playlist. RequiresRegularUserpermissions. - Update Metadata (
POST /playlist/update): Updates playlist name or description. - Delete Playlist (
POST/DEL /playlist/del/{id}): Removes a playlist and updates the creator's user record.
Sources: HX-Music-Server/include/api/PlaylistApi.hpp:46-95, HX-Music-Server/doc/api.md:155-177
Song Organization Endpoints
These endpoints manage the relationship between songs and playlists.
| Endpoint | Method | Parameter | Description |
|---|---|---|---|
/playlist/{id}/addMusic/{musicId} | POST | id, musicId | Appends a song to a playlist. |
/playlist/{id}/delMusic/{idx} | POST/DEL | id, idx | Removes a song by its index in the list. |
/playlist/updateMusicOrder/{id} | POST | id, IdListVO | Replaces the entire song order. |
Sources: HX-Music-Server/include/api/PlaylistApi.hpp:162-212, HX-Music-Server/doc/api.md:185-207
Query Endpoints
Retrieval endpoints allow fetching playlist data at different levels of detail.
The /playlist/select/{id} endpoint is unique because it performs a join-like operation, looking up the details for every musicId in the playlist's songIdList to return a complete PlaylistVO.
Sources: HX-Music-Server/include/api/PlaylistApi.hpp:96-141, include/pojo/vo/PlaylistInfoListVO.hpp:31-33
Client-Side Implementation
The HX-Music Client provides a PlaylistApi wrapper class that utilizes a NetSingleton to perform asynchronous communication.
Implementation Example: Fetching a Playlist
The client converts the raw JSON response from the server into a local Playlist object, mapping MusicVO objects to SongInformation structures.
// HX-Music-Client/include/api/PlaylistApi.hpp:56-88
static container::FutureResult<Playlist> selectById(uint64_t id) {
return NetSingleton::get().getReq("/playlist/select/" + std::to_string(id))
.thenTry([](container::Try<net::ResponseData> t) -> Playlist {
auto res = t.move();
auto jsonVo = api::getVO<vo::JsonVO<PlaylistVO>>(res);
auto playlistVO = *jsonVo.data;
return {
playlistVO.id,
playlistVO.name,
playlistVO.description,
// Maps MusicVO to SongInformation
};
});
}
Sources: HX-Music-Client/include/api/PlaylistApi.hpp:56-88, HX-Music-Client/include/pojo/Playlist.hpp:32-38
Permission and Validation Logic
The server enforces security and data integrity through interceptors and logic checks:
- Token Interceptor: Validates user identity and permission level (e.g.,
PermissionEnum::RegularUser). - Ownership Check: For operations like
addMusic, the server verifies the playlist ID exists in the user'screatedPlaylistarray. - Existence Check: Prevents adding duplicate songs to the same playlist.
- Bounds Checking: Validates that removal indices (
idx) are within the range of thesongIdList.
Sources: HX-Music-Server/include/api/PlaylistApi.hpp:163-178, HX-Music-Server/include/api/PlaylistApi.hpp:187-192
Conclusion
The Playlist API provides a robust set of endpoints for both high-level collection management and granular song organization. By separating metadata (PlaylistInfoVO) from full content (PlaylistVO), the system optimizes network traffic for browsing while providing comprehensive data for playback. The integration between PlaylistDAO and UserDAO ensures that user ownership and collection state remain synchronized across the application.