Skip to content

0.7 Active Playlist

Jump to bottom
Kurtis Nusbaum edited this page Jun 8, 2013 · 11 revisions

Back to 0.7 API

The following methods are used to interact with the active playlist for a given player.

Endpoints

/players/player_id/active_playlist

GET

Returns a JSON Object containing the song that is currently playing and all songs queued in the active playlist. The current song is in the from of a Played Active Playlist Entry JSON Object. The songs queued in the active playlist are in the form of a JSON Array of Active Playlist Entry JSON objects. The entire playlist is returned in the current expected order of play.

Also appended on the response is the current volume of the player (from 0 to 10) and it's current state (either playing or paused).

Example JSON response:

{
  "state" : state of the player (will either be playing or paused),
  "volume" : the current volume of the player (will be a value between 0 and 10),
  "current_song" : Played Active Playlist Entry JSON object,
  "active_playlist" : JSON array of Active Playlist Entries
}

If there is no current song being played, the current_song JSON object will be empty (i.e. {}). If there are no songs queued on the active playlist then the JSON array will have not entries.

POST

Modifies the active playlist associated with the player specified by player_id. This method must be provided with a JSON object of the following structure:

{
  "to_add" : JSON array of Simple Library Entry objects,
  "to_remove" : JSON array of Simple Library Entry objects
}

Success - HTTP 200:

The specified songs are successfully added and removed. If any of the to_add entries are already on the playlist, they will be upvoted. If any of the to_add entries happen to be the currently playing song, they will be ignored.

Errors

  • HTTP 400 - Bad Request - Your JSON was malformed
  • HTTP 403 - Forbidden - Header "X-Udj-Forbidden-Resaon" set to player-permission - Client did not have the proper permissions to either add or remove songs from the plyalist.
  • HTTP 404 - Not Found - Header "X-Udj-Missing-Resource" set to song - Any of the library entries to be added or removed can't be found. A JSON array of all the Simple Library Entry JSON objects that couldn't be found will also be returned.
  • HTTP 415 - Unsupported Media Type - The request must have content-type text-/json.

/players/player_id/active_playlist/songs/library_id/id

PUT

Adds the song specified by id belonging to the library specified by library_id to the active playlist on the player specified by player_id.

Success - HTTP 201: Created

If the given song is already on the playlist, the server will vote the song up on the users behalf. If the song is already playing, the request is just ignored.

Errors

  • HTTP 403 - Forbidden - Header "X-Udj-Forbidden-Resaons" set to player-permission - Client did not have the proper permissions to add songs to the plyalist.
  • HTTP 404 - Missing Resource - Header "X-Udj-Missing-Resource" set to song - Player doesn't have access to a song specified by the given library/id combination.

DELETE

Deletes the library entry with the id specified by the id parameter which is in the library specified by the library parameter from the active playlist of the player specified by the player_id parameter.

Success - HTTP 200:

Song is deleted from playlist.

Errors

  • HTTP 403 - Forbidden - Header "X-Udj-Forbidden-Resaons" set to player-permission - Client did not have the proper permissions to remove songs from the playlist.
  • HTTP 404 - Missing Resource - Header "X-Udj-Missing-Resource" set to song - Player doesn't have access to a song specified by the given library/id combination.

/players/player_id/active_playlist/songs/library_id/id/upvote

PUT

Votes up the song specified by id parameter in the library specified by the library_id parameter on the active playlist for the player specified by the player_id parameter. Users may only up vote once per song. Additional up vote requests are treated as duplicates and ignored. If a song that has been down voted is then up voted, the initial down vote is removed.

Success - HTTP 201: Created

Errors

  • HTTP 403 - Forbidden - Header "X-Udj-Forbidden-Resaons" set to player-permission - Client did not have the proper permissions to upvote songs on the playlist.
  • HTTP 404 - Missing Resource - Header "X-Udj-Missing-Resource" set to song - Player doesn't have access to a song with the given id in the specified library.

/players/player_id/active_playlist/songs/library_id/id/downvote

PUT

Votes down the song specified by id parameter in the library specified by the library_id parameter on the active playlist for the player specified by the player_id parameter. Users may only down vote once per song. Additional down vote requests are treated as duplicates and ignored. If a song that has been up voted is then down voted, the initial up vote is removed.

Success - HTTP 201: Created

Errors

  • HTTP 403 - Forbidden - Header "X-Udj-Forbidden-Resaons" set to player-permission - Client did not have the proper permissions to down vote songs on the playlist.
  • HTTP 404 - Missing Resource - Header "X-Udj-Missing-Resource" set to song - Player doesn't have access to a song with the given id in the specified library.
Clone this wiki locally