Skip to content

0.7 admin

Jump to bottom
murph edited this page Mar 12, 2013 · 1 revision

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/enabled_libraries - Follows List Semantics.

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

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.

/players/player_id/password

POST

Changes the password of the player specified by player_id. The new password should be specified with a JSON object of the following structure:

{
  "password" : "new password"
}

Errors

HTTP 400 - Bad Request - The given password does not conform to what ever standards the server has set for passwords. The response body will be "Bad password".

DELETE

Removes the password on the specified player.

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/location

POST

Changes the location of the player specified by player_id to the specified location. A JSON object of the following structure must be supplied:

{
  "postal_code" : "postal code of location" (required),
  "country" : "country of location" (required),
  "address" : "address of location" (optional),
  "locality" : "locality" (optional),
  "region" : "region of location" (optional)
}

Errors

HTTP 400 - Bad Request - The given location can not be found by the server. The response body set to 'Bad location'.

/players/player_id/sorting_algorithm <a id="sorting_algorithm"

[POST] /players/player_id/sorting_algorithm

Changes the sorting algorithm of the player specified by player_id to the specified algorithm id. The new sorting algorithm should be specified using the following JSON object:

{
  "sorting_algorithm_id" : "id of desired sorting algorithm"
}

If the given an unknown sorting algorithm id the server will return a 404 response with the X-Udj-Missing-Resource header set to sorting-algorithm.

[POST] /players/player_id/state

Sets the state of the player. The state should be specified using a JSON object of the following structure:

{
  "state" : "play" | "pause" | "inactive"
}

If state does not have one of the values or is not provided, a 400 response is returned.

[POST] /players/player_id/volume

Sets the current volume of the player. The parameter volume should be included and be a whole number in range 0 <= x <= 10 . The volume should be specified using the a JSON object of the following structure:

{
  "volume" : desired_volume
}

If the number provided is outside of the range a 400 response will be returned.

[PUT] /players/player_id/kicked_users/kick_user_id

This method kicks the user specified by the kick_user_id from the player specified by player_id. If no such user is currently participating with the player, an Http 404 response is returned with the X-Udj-Missing-Resource header set to user.

[PUT] /players/player_id/banned_users/user_id

This method bans the user specified by the user_id from the player specified by player_id. If the user is currently participating with the player, they are kicked. Upon successfully adding the user to a list of banned user, an Http 201 response is returned. If no such user exists an Http 404 response is returned with the X-Udj-Missing-Resource header set to user.

[DELETE] /players/player_id/banned_users/user_id

This method removes the ban on the user specified by the user_id from the player specified by player_id. If no such user was banned from the player, an Http 404 resposne is returned with the X-Udj-Missing-Resource header set to user.

[GET] /players/player_id/banned_users

Retrieves a JSON Array of User objects representing users that have been banned from the player.

Permissions

Permissions are used to control which users can preform which actions on a given player. Permissions are granted on a group by group basis, i.e. a given permission is assigned a set of groups. Each group is a list of users. Groups may overlap. If a user is in any of the groups assigned to a particular permission, that user is allowed perform the operation to wich the permission refers. If a given permission for a player has no groups assigned to it, any user participating with the player may perform the associated action. Valid player permissions are laid out in the documentation for the Player Permissions JSON object in the JSON Data Structures section.

[GET] /players/player_id/permissions

Retrieves a Player Permission objects representing all of the permission settings for this player.

[GET] /players/player_id/my_permission_groups

Returns a JSON array of Permission Group JSON objects which represent the permission groups for the player specified by player_id to which the calling user belongs.

[PUT] /players/player_id/permissions/permission_name/groups/group_name

Adds the group specified by group_name to the permission specified by permission_name. If the group to be added does not exist an HTTP 404 repsonse is returned with the X-Udj-Missing-Resource header set to permission-group. If the permission name specified does not exist an HTTP 404 response is returned with the X-Udj-Missing-Resource set to permission.

[DELETE] /players/player_id/permissions/permission_name/groups/group-name

Removes the group specified by group_name from the permission specified by permission_name. If the group to be removed isn't currently granted the specified permission an HTTP 404 repsonse is returned with the X-Udj-Missing-Resource header set to permission-group. If the permission name specified does not exist an HTTP 404 response is returned with the X-Udj-Missing-Resource set to permission.

[GET] /players/player_id/permission_groups

Retrieves a JSON Array of Permission Group objects representing all of the permission groups this player has.

[PUT] /players/player_id/permission_groups/group_name

Creates a new group specified by group_name for the player specified by player_id. On succuess this method returns an HTTP 201 response. If a group with the name speicifed already exists for the specified player an HTTP 409 response is returned.

[DELETE] /players/player_id/permission_groups/group_name

Deletes the group specified by group_name for the player specified by player_id. If the specified group does not exist on the specified player an HTTP 404 response is returned with the X-Udj-Missing-Resource header set to permission-group.

[GET] /players/player_id/permission_groups/group_name/members

Retrieves a JSON array of User JSON objects corresponding to the users who are members of the group specified by group_name on the player specified by player_id. If the specified group does not exist on the specified player an HTTP 404 response is returned with the X-Udj-Missing-Resource header set to permission-group.

[PUT] /players/player_id/permission_groups/group_name/members/user_id

Adds users to the group specified by group_name on the player specified by player_id. On success this method returns an HTTP 201 response. If the specified group does not exist on the specified player an HTTP 404 response is returned with the X-Udj-Missing-Resource header set to permission-group. If the specified user does not exist an HTTP 404 response is returned with the X-Udj-Missing-Resource header set to user.

[DELETE] /players/player_id/permission_groups/group_name/members/user_id

Removes users to the group specified by group_name on the player specified by player_id. The body of the request should contain a JSON array of user ids that should be removed from the group. If the specified group does not exist on the specified player an HTTP 404 response is returned with the X-Udj-Missing-Resource header set to permission-group. If the specified user does not exist an HTTP 404 response is returned with the X-Udj-Missing-Resource header set to user.

Clone this wiki locally