GET, POST, PUT, PATCH: HTTP methods to be used with each endpoint.
AUTH: When accessing endpoints marked AUTH, the client must provide the access token of the user.
ADMIN: When accessing endpoints marked ADMIN, the authenticated user must be an admin. Endpoints not marked ADMIN can be consumed by any authenticated user regardless of whether they are a normal or an admin user.
UserInfo, UserUpdate, SongInfo, SongUpdate, GenreInfo, GenreUpdate, PlaylistInfo, PlaylistUpdate: Go to section JSON Object Schemas to see what they are.
In this document, empty response on success actually means the following JSON response:
{
"success": true
}
There's no data other than a field indicating the response's status, hence the name, even though it is not literally empty.
POST /api/auth/register
Registers a new user.
UserUpdate.UserInfo.POST /api/auth/login
Returns token of a user, given their credentials.
Payload:
{
"email": "[email protected]",
"password": "12345678"
}
Response on success: UserInfo plus one field
named token, which is the authentication token used for
AUTH routes.
POST AUTH /api/auth/logout
Invalidates a token of an authenticated user. The invalidated token can no longer be used.
GET /api/users
Returns a list of all users in the system.
Empty payload.
Response on success:
{
"list": [ ... ]
}
where [ ... ] is a list of UserInfo
objects.
GET /api/users/{user_id}
Returns information of a user, given their ID.
UserInfo.POST /api/users/signup OR POST /users
Same as /api/auth/register.
PUT AUTH /api/users/{user_id}
Updates information of a user, given their ID and the updated information.
Every user, including every admin, cannot update information of another user.
UserUpdate.UserInfo.DELETE AUTH /api/users/{user_id}
Deregisters, or deletes a user account, given their ID.
Normal users can only delete their own accounts, not others'.
Admin users can delete any account.
GET AUTH /api/users/{user_id}/favorite/playlists
Retrieves a list of this user's favorite playlists.
The specified user must be the currently-authenticated user.
Empty payload.
Response on success:
{
"list": [ ... ]
}
where [ ... ] is a list of PlaylistInfo
objects.
POST AUTH /api/users/{user_id}/favorite/playlists/{playlist_id}
Marks an existing playlist as one of the user's favorites.
The specified user must be the currently-authenticated user.
DELETE AUTH /api/users/{user_id}/favorite/playlists/{playlist_id}
Removes a playlist from the user's favorite list.
The specified user must be the currently-authenticated user.
GET AUTH /api/users/{user_id}/favorite/songs
Retrieves a list of this user's favorite songs.
The specified user must be the currently-authenticated user.
Empty payload.
Response on success:
{
"list": [ ... ]
}
where [ ... ] is a list of SongInfo
objects.
POST AUTH /api/users/{user_id}/favorite/songs/{song_id}
Marks an existing song as one of the user's favorites.
The specified user must be the currently-authenticated user.
DELETE AUTH /api/users/{user_id}/favorite/songs/{song_id}
Removes a song from the user's favorite list.
The specified user must be the currently-authenticated user.
GET /api/users/{user_id}/own/playlists
If the specified user is the currently-authenticated user: returns all playlists that the user has created.
Otherwise: returns only the playlists that the user has created AND IS PUBLIC.
Empty payload.
Response on success:
{
"list": [ ... ]
}
where [ ... ] is a list of PlaylistInfo
objects.
GET /api/playlists
Returns a list of all playlists in the system that the currently-authenticated user has the right to access.
If the user has not logged in: only public playlists are returned.
If the user has logged in: only public playlists and all of his playlists are returned.
In neither case will other users' private playlists be returned.
Empty payload.
Response on success:
{
"list": [ ... ]
}
where [ ... ] is a list of PlaylistInfo
objects.
GET /api/playlists/{playlist_id}
Returns information of a playlist, given its ID.
If the playlist is not public, only the authenticated user
who owns it can access its information. See details about
playlist ownership in PlaylistInfo.
PlaylistInfo.POST AUTH /api/playlists
Creates a new playlist.
PlaylistUpdate.PlaylistInfo.PUT AUTH /api/playlists/{playlist_id}
Updates an existing playlist, given its ID.
Only the authenticated user who owns the playlist can
modify it. See details about playlist ownership in
PlaylistInfo.
PlaylistUpdate.PlaylistInfo.DELETE AUTH /api/playlists/{playlist_id}
Deletes an existing playlist, given its ID.
Only the authenticated user who owns the playlist can
delete it. See details about playlist ownership in
PlaylistInfo.
GET /api/playlists/{playlist_id}/songs
Retrieves all of this playlist's songs.
If the playlist is not public, only the authenticated user
who owns it can access its information. See details about
playlist ownership in PlaylistInfo.
Empty payload.
Response on success:
{
"list": [ ... ]
}
where [ ... ] is a list of SongInfo
objects.
POST AUTH /api/playlists/{playlist_id}/songs/{song_id}
Adds a song to an existing playlist.
Only the authenticated user who owns the playlist can
modify it. See details about playlist ownership in
PlaylistInfo.
DELETE AUTH /api/playlists/{playlist_id}/songs/{song_id}
Removes a song from an existing playlist.
Only the authenticated user who owns the playlist can
modify it. See details about playlist ownership in
PlaylistInfo.
GET /api/genres
Returns names of all genres available in the system.
Empty payload.
Response on success:
{
"list": [ "..." ]
}
where [ ... ] is a list of GenreInfo
objects.
GET /api/genres/{genre_id}
Returns information of a genre.
GenreInfo.POST AUTH ADMIN /api/genres
Creates a new genre.
GenreUpdate.GenreInfo.PUT AUTH ADMIN /api/genres/{genre_id}
Updates an existing genre.
GenreUpdate.GenreInfo.DELETE AUTH ADMIN /api/genres/{genre_id}
Deletes an existing genre.
GET /api/genres/{genre_id}/songs
Retrieves a list of this genre's songs.
Empty payload.
Response on success:
{
"list": [ ... ]
}
where [ ... ] is a list of SongInfo objects.
GET /api/artists
Returns a list of all artists available in the system.
Empty payload.
Response on success:
{
"list": [ ... ]
}
where [ ... ] is a list of ArtistInfo
objects.
GET /api/artists/{artist_id}
Returns information of an artist, given their ID.
ArtistInfo.POST AUTH ADMIN /api/artists
Adds a new artist.
ArtistUpdate.ArtistInfo.PUT AUTH ADMIN /api/artists/{artist_id}
Updates an existing artist.
ArtistUpdate.ArtistInfo.DELETE AUTH ADMIN /api/artists/{artist_id}
Deletes an existing artist.
GET /api/artists/{artist_id}/songs
Retrieves a list of this artist's songs.
Empty payload.
Response on success:
{
"list": [ ... ]
}
where [ ... ] is a list of SongInfo
objects.
GET /api/songs
Returns a list of all songs in the system.
Empty payload.
Response on success:
{
"list": [ ... ]
}
where [ ... ] is a list of SongInfo
objects.
GET /api/songs/{song_id}
Returns information of a song. Do not increment streams.
SongInfo.POST AUTH ADMIN /api/songs
Adds a new song.
SongUpdate.SongInfo.PUT AUTH ADMIN /api/songs/{song_id}
Updates information of a song.
SongUpdate.SongInfo.DELETE AUTH ADMIN /api/songs/{song_id}
Deletes a song.
GET /api/songs/{song_id}/listen
Returns information of the song, and increment its stream count.
SongInfo.GET /api/songs/{song_id}/artists
Retrieves a list of this song's artists.
Empty payload.
Response on success:
{
"list": [ ... ]
}
where [ ... ] is a list of ArtistInfo
objects.
POST AUTH ADMIN /api/songs/{song_id}/artists/{artist_id}
Adds an artist to this song's list of artists.
DELETE AUTH ADMIN /api/songs/{song_id}/artists/{artist_id}
Removes an artist from this song's list of artists.
GET /api/songs/{song_id}/genres
Retrieves a list of this song's genres.
Empty payload.
Response on success:
{
"list": [ ... ]
}
where [ ... ] is a list of GenreInfo
objects.
POST AUTH ADMIN /api/songs/{song_id}/genres/{genre_name}
Adds a genre to this song's list of genres.
DELETE AUTH ADMIN /api/songs/{song_id}/genres/{genre_name}
Removes a genre from this song's list of gerres.
This web project uses Algolia for searching (which is used by the search bar in the frontend).
After adding several searchable objects, we have to access the Indexing API endpoints to update Algolia records.
PATCH AUTH ADMIN /api/index/songs, /api/index/songs?reset=true
Updates Algolia records for songs, so that the newly-added songs could appear in the frontend's search bar when being searched for.
By default, this won't remove records of deleted songs. Add query
paramater ?reset=true if you want to also remove those unused
records.
The following object schemas are listed in their alphabetical order.
{
"success": true,
"id": "123",
"name": "Frederic Chopin",
"image_link": "...",
"added_at": "When was this artist added. See notes about datetimes.",
"updated_at": "When was this artist last updated. See notes about datetimes.",
"added_by": "ID of the user that added this artist",
"updated_by": "ID of the user that last updated this artist"
}
{
"name": "Alan Walker",
"image_link": "The link to image, or null"
}
When adding a new artist, all the fields are required. Otherwise, specify the updated fields only.
{
"success": true,
"id": 11,
"name": "Classical",
"image_link": "The link to image, or null",
"added_at": "When was this genre added. See notes about datetimes.",
"updated_at": "When was this genre last updated. See notes about datetimes.",
"added_by": "ID of the user that added this genre",
"updated_by": "ID of the user that last updated this genre"
}
{
"name": "Classical Music",
"image_link": "The link to image, or null"
}
When adding a new genre, all the fields are required. Otherwise, specify the updated fields only.
{
"success": true,
"id": 3003,
"name": "My Playlist",
"image_link": "The link to image, or null",
"owned_by": "ID of the user that added this playlist, which is also the only one that could update it",
"is_public": true, // or false
"added_at": "When was this playlist added. See notes about datetimes.",
"updated_at": "When was this playlist last updated. See notes about datetimes."
}
{
"name": "Our Playlist",
"image_link": "The link to image, or null",
"is_public": false // or true
}
When adding a new playlist, all the fields are required. Otherwise, specify the updated fields only.
{
"success": true,
"id": "123456",
"name": "Happy Birthday",
"image_link": "The link to image, or null",
"audio_link": "A link that can be embedded into <audio> HTML tag",
"added_at": "When was this song added. See notes about datetimes.",
"updated_at": "When was this song last updated. See notes about datetimes.",
"added_by": "ID of the user that added this song",
"updated_by": "ID of the user that last updated this song",
"streams": 15000
}
{
"name": "Happy Birthday to You",
"audio_link": "See SongInfo",
"image_link": "The link to image, or null"
}
When adding a new song, all the fields are required. Otherwise, specify the updated fields only.
{
"success": true,
"id": "13680015",
"email": "[email protected]",
"name": "User's Full Name",
"image_link": "The link to image, or null",
"is_admin": false, // or true
"deleted": false // or true
}
{
"email": "[email protected]",
"password": "123456789",
"name": "User's Full Name",
"image_link": "The link to image, or null"
}
In case of registering a new user, all the fields are required. Otherwise, specify the updated fields only.