Skip to content

0.7 Player Administration

Jump to bottom
Kurtis Nusbaum edited this page Aug 26, 2013 · 40 revisions

Back to 0.7 API

The following methods are used to administrate various aspects of a UDJ player. In any of the following methods, if the player_id specified does not exist, an HTTP 404 response is returned with the X-Udj-Missing-Resource header set to player.

Endpoints:

## /players/`player_id`/password

POST

Changes the password of the player specified by player_id to the string specified by the password JSON parameter.

Success - HTTP 200:

The password is changed.

Errors

  • Http 400 - Bad Request - The password does not meet the strength requirements of the server
  • Http 403 - Forbidden - Header "X-Udj-Forbidden-Reason" set to player-permission - Client doesn't have proper missions to modify the player's password.
  • HTTP 404 - Not Found - Header "X-Udj-Missing-Resource" set to player - The player specified by player_id does not exist.
  • HTTP 415 - Unsupported Media Type - The request must have content-type text-/json.

DELETE

Removes the password from the player.

Sucess - HTTP 200:

The password is removed.

Errors

  • Http 403 - Forbidden - Header "X-Udj-Forbidden-Reason" set to player-permission - Client doesn't have proper missions to modify the player's password.
  • HTTP 404 - Not Found - Header "X-Udj-Missing-Resource" set to player - The player specified by player_id does not exist.
## /players/`player_id`/location

POST

Changes the location of the player specified by player_id the specified, JSON-defined location. Example JSON:

"location" :
    {
      "address" : "1601 Willow Road",
      "locality" : "Menlo Park",
      "region" : "California",
      "postal_code" : "94025",
      "country" : "United States"
    },

Success - HTTP 200:

The location is changed.

Errors

  • HTTP 400 - Bad Request - Response body "Bad location" - The given location can not be found by the server.
  • Http 403 - Forbidden - Header "X-Udj-Forbidden-Reason" set to player-permission - Client doesn't have proper missions to modify the player's location.
  • HTTP 404 - Not Found - Header "X-Udj-Missing-Resource" set to player - The player specified by player_id does not exist.
  • HTTP 415 - Unsupported Media Type - The request must have content-type text-/json.

DELETE

Removes the location from the player.

Sucess - HTTP 200:

The location is removed.

Errors

  • Http 403 - Forbidden - Header "X-Udj-Forbidden-Reason" set to player-permission - Client doesn't have proper missions to modify the player's password.
  • HTTP 404 - Not Found - Header "X-Udj-Missing-Resource" set to player - The player specified by player_id does not exist.
## /players/`player_id`/sorting_algorithm

POST

Changes the sorting algorithm use by the player specified by player_id to the-JSON specified sorting

alrogithm. Example JSON:

{
  "sorting_algorithm_id" : "5"
}

Success - HTTP 200:

The sorting algorithm is changed.

Errors

  • HTTP 400 - Bad Request - The given location can not be found by the server.
  • Http 403 - Forbidden - Header "X-Udj-Forbidden-Reason" set to player-permission - Client doesn't have proper missions to modify the player's location.
  • HTTP 404 - Not Found - Header "X-Udj-Missing-Resource" set to player - The player specified by player_id does not exist.
  • HTTP 404 - Not Found - Header "X-Udj-Missing-Resource" set to sorting-algorithm - There was not sorting algorithm with the specified id.
  • HTTP 415 - Unsupported Media Type - The request must have content-type text-/json.
## /players/`player_id`/state

POST

Changes the player state of the player specified by player_id to the JSON-specified sorting. The state must be one of the valid states specified by the Player JSON Object.

Example JSON:

{
  "state" : "pause"
}

Success - HTTP 200:

The state is changed.

Errors

  • HTTP 400 - Bad Request - The state given was not valid
  • Http 403 - Forbidden - Header "X-Udj-Forbidden-Reason" set to player-permission - Client doesn't have proper missions to modify the player's state.
  • HTTP 404 - Not Found - Header "X-Udj-Missing-Resource" set to player - The player specified by player_id does not exist.
  • HTTP 415 - Unsupported Media Type - The request must have content-type text-/json.
## /players/`player_id`/volume

POST

Changes the volume of the player specified by player_id to the JSON-specified sorting.

Example JSON:

{
  "volume" : 5
}

Success - HTTP 200:

The volume is changed.

Errors

  • HTTP 400 - Bad Request - A bad volume is given
  • Http 403 - Forbidden - Header "X-Udj-Forbidden-Reason" set to player-permission - Client doesn't have proper missions to modify the player's state.
  • HTTP 404 - Not Found - Header "X-Udj-Missing-Resource" set to player - The player specified by player_id does not exist.
  • HTTP 415 - Unsupported Media Type - The request must have content-type text-/json.

/players/player_id/enabled_libraries

enabled_libraries is a list of Library objects that are enabled on the player specified by player_id.

Follows List Semantics

Errors for PUT:

  • HTTP 403 - Forbidden - The calling user does not have permission to enable libraries on the player. Header X-Udj-Forbidden-Reason is set to player-permission.
  • HTTP 403 - Forbidden - The owner of the player does not have read access to the library being enabled. Header X-Udj-Forbidden-Reason is set to library-permission.

Errors for DELETE:

  • HTTP 403 - Forbidden - The calling user does not have permission to disable libraries on the player.
  • HTTP 404 - Not Found - There is no enabled library with matching id. The header X-Udj-Missing-Resource header set to library.

Errors

  • HTTP 404 - Not Found - The player never had a password to begin with. Header X-Udj-Missing-Resource header is set to password.

/players/player_id/kick_user/user_id

PUT

Kick the specified user from the specified player.

Errors

  • HTTP 404 - Not Found - No such user is currently participating with the player - Header X-Udj-Missing-Resource header is set to user.

/players/player_id/banned_users

A list of User ids that are banned from this player.

Follows List Semantics

/players/player_id/banned_music

A list of Library Entry ids that are banned from this player.

Used to ban and unban songs a given player.

Follows List Semantics

Clone this wiki locally