Skip to main content

How to Access Favorites

When a user likes a song, they might want to keep it in their favorites to easily retrieve it later on. Karaoke-api offers the feature to save liked songs.

Requirements​

You must have a valid API key and Bearer Token. For information on how to get the token, refer to Generating Access Tokens.

To run the tutorial, you must download the full OpenAPI specification and then import it into an API testing platform. For this tutorial, we will be using Postman API. For information on how to use Postman, refer to their documentation.

Saving a song in their favorites​

To save a liked song, we must call PUT \v2\profile\favorites\songs\{song_id} where the {song_id} represents the id of the song we want to add to our favorites.

For example, the following request would add the song KAR:G:1001 to the favorites.

PUT \v2\profile\favorites\songs\KAR:G:1001

Note that the maximum number of songs that can be liked is 1000. Once the limit is reached, an error 422 will be returned and the user will have to remove songs from their favorites to add new ones.

Retrieving their favorites​

To retrieve the user liked songs, we must call GET \v2\profile\favorites\songs. We have the option of using the following query parameters:

  • size: (Optional) Set the number of entries to return in the results. By default, 10 songs are returned.
  • page: (Optional) Enter the specific results page number to return. By default, the first page is returned (page=0).

Result​

The endpoint returns a list of songs that were liked by the user.

Figure 1: Step 1 sample response

[
  {
    "thumbnails": {
      "album": "{thumbnail filePath}"
    },
    "id": "KAR:G:2411566",
    "title": "What's It Gonna Be",
    "duration_sec": 321,
    "genre": {
      "id": "3",
      "label": "R&B/Hip-Hop"
    },
    // other paramaters
    "added_date": "2022-04-25"
    // other parameters
  },
  {
    "thumbnails": {
      "album": "{thumbnail filePath}"
    },
    "id": "KAR:G:3259333",
    "title": "We Don't Talk About Bruno (Duet)",
    "duration_sec": 213,
    "genre": {
      "id": "12",
      "label": "Disney"
    },
    // other parameters
    "added_date": "2022-04-08"
    // other parameters
  },
  {
    "thumbnails": {
      "album": "{thumbnail filePath}"
    },
    "id": "KAR:G:3583",
    "title": "From This Moment On (Duet)",
    "duration_sec": 225,
    "genre": {
      "id": "6",
      "label": "Country"
    },
    // other parameters
    "added_date": "2022-03-03"
    // other parameters
  },
  {
    "thumbnails": {
      "album": "{thumbnail filePath}"
    },
    "id": "KAR:G:7556",
    "title": "That's Another Story (Duet)",
    "duration_sec": 210,
    "genre": {
      "id": "6",
      "label": "Country"
    },
    // other parameters
    "added_date": "2021-12-01"
    // other parameters
  },
  {
    "thumbnails": {
      "album": "{thumbnail filePath}"
    },
    "id": "KAR:G:2542509",
    "title": "Have Yourself A Merry Little Christmas",
    "duration_sec": 217,
    "genre": {
      "id": "1",
      "label": "Holiday"
    },
    // other parameters
    "added_date": "2021-08-20"
    // other parameters
  }
]

Finding if a song is in their favorites​

To know if a song is liked, we must call GET \v2\profile\favorites\songs\contain\{song_id} where the {song_id} represents the id of the songs we want to check.

For example, we would use the following request to know if the song KAR:G:1001 is in the favorites.

GET \v2\profile\favorites\songs\contain\KAR:G:1001

Result​

The request returns true if the song is in the favorites or false otherwise.

Removing a favorite​

To remove a song from the list of liked songs, we must call DELETE \v2\profile\favorites\songs\{song_id} where the {song_id} represents the id of the songs we want to remove from the favorites.

For example, the following request would remove the song KAR:G:1001 from the favorites.

DELETE \v2\profile\favorites\songs\KAR:G:1001

Result​

A status code of 204 means the song was removed successfully from the favorites.

Clearing the favorites​

There's also an endpoint to clear all favorites of a user. To do so, we must call DELETE \v2\profile\favorites\songs.

Result​

A status code of 204 means the favorites were removed successfully.