Discovery Endpoints
The DiscoverController provides endpoints for discovering tracks, albums, and artists based on
specified criteria such as genres or connections between artists.
Controller Route: /api/discover
All routes within the DiscoverController are prefixed by /api/discover/.
Summary of Endpoints
| Endpoint | Method | Description | Authorization |
|---|---|---|---|
/api/discover/tracks |
GET | Discover tracks based on input ids. | Admin, User |
/api/discover/albums |
GET | Discover albums based on input ids. | Admin, User |
/api/discover/artists |
GET | Discover artists based on input ids. | Admin, User |
/api/discover/time |
GET | Discover time-based tracks within a specified time window. | Admin, User |
Discover Tracks
This endpoint allows users to discover tracks based on provided track ids.
Details:
- Endpoint:
/api/discover/tracks - Method:
GET - Authorization: JWT with Admin or User role
Parameters:
- ids (
List<string>, required): A list of track IDs to base the discovery on. - orderByFavorites (bool, optional): If true, weighs tracks shuffle by user favorites(high rating, lots of plays)
- orderByDiscovery (bool, optional): If true, weighs track shuffle by tracks with less plays.
- count (int, optional): The maximum number of tracks to return (default is 100).
- enableTrackLinks (bool, optional): If true, enables TrackLinks.
- includeArtists (bool, optional): If true, includes related artist tracks in the results.
- includeGenres (bool, optional): If true, includes tracks of the same genres.
Responses:
- 200 OK: Returns a list of discovered Tracks.
- 400 Bad Request: Invalid parameters or request.
Example Request (using curl):
curl -X GET "https://your-melon-server.com/api/discover/tracks?ids=track1,track2&orderByFavorites=true&count=10" \
-H "Authorization: Bearer <User-JWT>"
Discover Albums
This endpoint allows users to discover albums based on album ids.
Details:
- Endpoint:
/api/discover/albums - Method:
GET - Authorization: JWT with Admin or User role Parameters:
- ids (
List<string>, required): A list of album IDs to base the discovery on. - shuffle (bool, optional): If true, shuffles the returned albums.
- count (int, optional): The maximum number of albums to return (default is 100).
- page (int, optional): The page number of the results (used for pagination).
- includeArtists (bool, optional): If true, includes albums by connected artists.
- includeGenres (bool, optional): If true, includes albums from the same genres.
Responses:
- 200 OK: Returns a list of discovered Albums.
- 400 Bad Request: Invalid parameters or request.
Example Request (using curl):
curl -X GET "https://your-melon-server.com/api/discover/albums?ids=album1,album2&count=5&includeArtists=true" \
-H "Authorization: Bearer <User-JWT>"
Discover Artists
This endpoint allows users to discover artists based on artist ids.
Details:
- Endpoint:
/api/discover/artists - Method:
GET - Authorization: JWT with Admin or User role
Parameters:
- ids (
List<string>, required): A list of artist IDs to base the discovery on. - count (int, optional): The maximum number of artists to return (default is 100).
- page (int, optional): The page number of the results (used for pagination).
- shuffle (bool, optional): If true, shuffles the returned artists.
- includeConnections (bool, optional): If true, includes connected artists.
- includeGenres (bool, optional): If true, includes artists from the same genres.
Responses:
- 200 OK: Returns a list of discovered Artists.
- 400 Bad Request: Invalid parameters or request.
Example Request (using curl):
curl -X GET "https://your-melon-server.com/api/discover/artists?ids=artist1,artist2&count=10&includeGenres=true" \
-H "Authorization: Bearer <User-JWT>"
Discover Time-Based Tracks
This endpoint allows users to discover tracks that are similar to those played around a specified time.
Details:
- Endpoint:
/api/discover/time - Method:
GET - Authorization: JWT with Admin or User role
Parameters:
- time (string, required): The specific time (e.g., "10:22:00AM") around which tracks will be discovered.
- span (int, optional): The time span in minutes (default is 5).
- count (int, optional): The maximum number of tracks to return (default is 100).
- enableTrackLinks (bool, optional): If true, enables track links.
- includeArtists (bool, optional): If true, includes tracks by related artists.
- includeGenres (bool, optional): If true, includes tracks of the genres.
- includeRecent (bool, optional): If true, includes recently played tracks.
Responses:
- 200 OK: Returns a list of discovered Tracks.
- 400 Bad Request: Invalid parameters or request.
Example Request (using curl):
curl -X GET "https://your-melon-server.com/api/discover/time?time=2023-09-15T12:00:00&span=10&count=10&includeArtists=true" \
-H "Authorization: Bearer <User-JWT>"