-
Notifications
You must be signed in to change notification settings - Fork 17
UDJ REST API 0.7
This page serves as general documentation for the UDJ REST API.
#JSON Data Structures
{
"id" : Id of user (string),
"username" : User name of the user (string),
"first_name" : Users first name (string),
"last_name" : Users last name (string)
}
{
"id" : unique player id (string),
"name": name of player (string),
"owner" : User JSON Object representing the owner of the player,
"has_password" : true if the player has a password, false otherwise,
"location" : { (optional)
"latitude" : the latitude of the location of the player (number),
"longitude" : the longitude of the location of the player (number),
"address" : address of player (string),
"locality" : Locality/City of player (string),
"region" : State, Region, or Providence of player (string),
"postal_code" : postal code of player (string),
"country" : country of player (string)
},
"sorting_algo" : A Sorting Algorithm JSON object representing the sorting algorithm this player is using for the playlist,
"num_active_users": Currently how many active users are participating with this player (number),
"size_limit" : The maximum number of active participants that can be in a player at a given time. Note: if the player has no size limit, attribute will not be present (number).
"enabled_libraries" : A JSON Array of Library JSON objects representing enabled libraries for this player.
"permissions" : A Player Perimissions JSON Object describing the permissions on the player.
}
{
"create_song_set" : JSON Array of Group names,
"control_playback" : JSON array of group names,
"control_volume" : JSON array of group names,
"set_sorting_algorithm" : JSON array of group names,
"set_location" : JSON array of group names,
"set_password" : JSON array of group names,
"kick_users" : JSON array of group names,
"ban_users" : JSON array of group names,
"active_playlist_remove_songs" : JSON array of group names,
"active_playlist_add_songs" : JSON array of group names,
"active_playlist_upvote" : JSON array of group names,
"active_playlist_downvote" : JSON array of group names,
"enable_library" : JSON array of group names,
"disable_library" : JSON array of group names,
"modify_permission_groups" : JSON array of group names,
"create_event" : JSON array of group names
"host_event" : JSON array of group names
"modify_event" JSON array of group names
}
{
"name" : name of group,
"users" : JSON array of user ids
}
{
"id" : id of library (string),
"name" : name of library (string),
"description" : short description of library (string),
"pub_key" : 2048 bit RSA public key for this library,
"read_permission" : "none" | "owner" | "admins" | "user" | "public",
"write_perimssion" : "none" | "owner" | "admins" | "user" | "public"
}
{
"id" : id of library entry (string),
"library_id" id of the library to which this library entry belongs (string),
"title" : name of the song (string),
"artist" : name of the artist (string),
"album" : name of album (string),
"track" : number of track (number),
"genre" : genre of the song (string),
"duration" : duration of song in seconds (number)
}
{
"id" : id of library entry (string),
"library_id" id of the library to which this library entry belongs (string),
}
{
"song" : LibraryEntry JSON object,
"upvoters" : A JSON array of User objects who have upvoted this song,
"downvoters" : A JSON array of User objects who have downvoted this song,
"time_added" : Time the entry was added (string),
"adder" : User JSON Object representing the user who added the player,
"user_priority" : Priority of the song for a given user
}
{
"song" : LibraryEntry JSON object,
"upvoters" : A JSON array of User objects who have upvoted this song,
"downvoters" : A JSON array of User objects who have downvoted this song,
"time_added" : Time the entry was added (string),
"time_played" : Time the entry started playing (string),
"adder" : User JSON Object representing the user who added the player
"user_priority" : Priority of the song for a given user
}
{
"name" : Name of song set (string),
"description" : a short description of the song set (string),
"songs" : a JSON Array of Library Entry JSON Objects,
"owner" : a User JSON Object representing the owner of the song set,
"date_created" : The date the song set was created (string)
}
{
"id" : id of sorting algorithm (string),
"name" : name of sorting algorithm (string),
"description" : short description of how the sorting algorithm works (string)
"uses_adder" : a boolean indicating whether or not this algorithm takes the song adder into account when sorting,
"uses_time_added" : a boolean indicating whether or not this algorithm takes time added into account when sorting,
"uses_upvotes" : a boolean indicating whether or not this algorithm takes upvotes into account when sorting,
"uses_downvotes" : a boolean indicating whether or not this algorithm takes downvotes into account when sorting,
"uses_priority" : a boolean indicating whether or not this algorithm takes priorities into account when sorting,
}
{
"id" : id of event (string),
"name" : name of event,
"player_id" : id of player the event will be on,
"start_time" : start time of event,
"end_time" end time of event
}
Methods are presented in the following form: [METHOD_TYPE] uri/to/method. All timestamps are in UTC time and must be formatted according to the ISO 8601 format using this format:
YYYY-mm-ddTHH:MM:ss
Creates a new user. It should be given the following JSON:
{
"username" : desired username
"email" : email address to associate with the user
"password" : desired password
}
Upon successful creation this method returns a 201 response. If the desired username is already taken, an Http 409 response is returned with the X-Udj-Conflict-Resource header set to username. If there already exists a user with the given username an Http 409 response is returned with the X-Udj-Conflict-Resource header set to email. If the password given does not meet the server's password strength requirements, the email is invalid, or the username is invalid an Http 406 response is returned. If the JSON is malformed, an Http 400 response is returned.
The auth method allows a client to authenticate with the webserver and must be executed before any further communication between the client and the server can take place. Included in the post information should be two parameters: username and password. If the username and password combination is valid, the server will return a JSON object containing a
ticket hash and the user's assigned id.
Example response from the server:
{
"ticket_hash" : assigned ticket hash,
"user_id" : id
}
All subsequent requests must be sent with the given ticket in the header like so:
X-Udj-Ticket-Hash: assigned ticket hash
If any of the methods specified below are called without this ticked in the header, an HTTP 401 response will be returned. If any of the methods below are called with an invalid ticket in the header, an HTTP 401 response will be returned. In either case the WWW-Authenticate header will be set to the value ticket-hash. Ticket's may become invalid at any time and a given server implementation may choose however long it wishes to consider a ticket valid.
If the username and password combination is invalid a 401 response will be returned. The WWW-Authenticate header will be set to password.
Retrieves the public key for the user specified by user_id. If no user matching user_id exists, an HTTP 404 is returned with the X-Udj-Missing-Resource header set to user.
Retrieves the public key of the user calling this method.
Retrieves the private key of the user calling this method.
Retrieves a JSON Array of available playlist sorting algorithms JSON Objects.
This method allows a client to retrieve a list of nearby, active players based on the current location of client. Supplied are the latitude and longitude which specify where to search for players (i.e. the location of the client). This method returns a JSON array of player objects.
An optional radius parameter may be specified, thus indicating the desired search radius for the
query. The radius should be specified in kilometers. If no radius is specified, the server will
fallback to it's own desired default.
An optional max_results parameter may be specified, thus indicating the desired maximum results
for the server to return.
If the server finds the specified radius unaccepatable (i.e. it's too big or too small), an
HTTP 406 response will be returned with the header X-Udj-Not-Acceptable-Reason set to bad-radius.
The response will also contain a JSON object indicating the range (in dijkstra notation) of
acceptable radii. The JSON object will have the following form:
{
"min_radius" : Minimum search radius in kilometers (inclusive),
"max_radius" : Maximum search radius in kilometers (exclusive)
}
This method allows a client to retrieve a list of all active players that have a name similar to the name parameter. A JSON array of Player objects is returned. If no players are found matching the specified name, an array of length zero will be returned.
An optional max_results parameter may be specified, thus indicating the desired maximum results for the server to return.
Creates a new player. The owner is set to the user calling this method. This method should be given the following JSON:
{
"name" : name of player,
"location":{
"address": Address where player is located (optional),
"locality": Locality/City where player is located (optional),
"region": Regions, State, or Providence where player is located (optional),
"postal_code": Postal code of where player is located,
"country": Country in which the player is located,
},
"password" : password,
"sorting_algorithm_id" : id of the sorting algorithm to be used for the playlist
}
The location, password, sorting_algorithm_id, and external_library_ids attributes are optional. If successful, a 201 response will be returned with the body set to a Player JSON object representing the player that was created.
If the user already has a player with the same name, a 409 response is returned. Note that the content-type header must be set to text/json, or the server will return a 415 error. If the JSON is malformed a 400 response will be returned with the response "Bad JSON". If no name for the player is given, a 400 repsonse will be returned with the response "No name given". If the location JSON is malformed, a 400 response will be returned with the response "Bad location". If the location given can't be found by the server, a 400 response will be returned with the resposne "Location not found". If the given password does not conform to what ever standards the server has set for passwords, a 400 response will be returned withe the body "Bad password". If the sorting_algorithm specified is unknown to the server, a 404 response will be returned with the X-Udj-Missing-Resource header set to sorting-algorithm.
Enabled the library specified by library_id for the player specified by player_id. The calling user must have permission to enable libraries on the player and must have read access to the library
they're enabling otherwise an Http 403 response is returned.
Disables the library specified by library_id for the player specified by player_id. The calling user must permission to disble libraries on the player otherwise an Http 403 response is returned.
Changes the password of the player specified by player_id to the string specified by the password POST parameter. If the given password does not conform to what ever standards the server has set for passwords, a 400 response will be returned with the body "Bad password".
Removes the password on the player specified by the player_id. If the player never had a password to begin with a 404 response is retured with the X-Udj-Missing-Resource header set to password.
Changes the location of the player specified by player_id to the specified location. That means the POST must contain the following parameters: postal_code and country. The following additional parameters can be given to increase the accuracy of the resolved location: address, locality, and region. If the given location can not be found by the server then a 400 response is returned with the body set to 'Bad location'
Changes the sorting algorithm of the player specified by player_id to the specified algorithm id. That means the POST must contain the sorting_algorithm_id parameter. 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.
Sets the state of the player. A call to this method must include a parameter called state. state must be one of the following values:
- playing
- paused
- inactive
If state does not have one of the values or is not provided, a 400 response is returned.
Sets the current volume of the player. The parameter volume should be included and be a whole number in range 0 <= x <= 10 . If no number is provided, or a number outside of the range is provided a 400 response will be returned.
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.
This method bans the user specified by the ban_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.
This method removes the ban on the user specified by the banned_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.
Retrieves a JSON Array of User objects representing users that have been banned from the player.
Retrieves a Player Permission objects representing all of the permission settings for this player.
Adds groups to the permission specified by permission_name. The groups should be specified by their names in a JSON array.
For example: if we wanted to add the groups "friends" and "admins" to the enable_library permission we would use
/udj/0_7/players/player_id/permissions/enable_library
With the body set to the JSON:
["friends", "admins"]
Removes groups from the permission specified by permission_name. The groups should be specified by their names in a JSON array.
For example: if we wanted to remove the groups "enemies" and "non-admins" from the disable_library permission we would use:
/udj/0_7/players/player_id/permissions/disable_library
With the body set to the JSON:
["enemies", "non-admins"]
Changes the permissions for the player. This call takes to parameters:
-
permissionsis a JSON array of each permission to change. -
groupsis a JSON array of the group names that should be assigned to each permission in thepermissionsarray.
Example: If we wanted to set set_location to only be allowed for members of the admin group and the ban_users to only be allowed for the owner and admin groups the following post parameters
would be used:
permissions=["set_location", "ban_users"]&groups=[["admin"], ["owner","admin"]]
Retrieves a JSON Array of Permission Group objects representing all of the permission groups this player has.
Creates a new group specified by group_name for the player specified by player_id.
Deletes the group specified by group_name for the player specified by player_id.
Adds and removes the groups specified by the to_add and to_remove parameters. The values for these parameters should be JSON arrays containing the group names to be added and removed respectively.
Retrieves a JSON array of user ids corresponding to the users who are members of the group specified by group_name on the player specified by player_id.
Adds 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 added to the group.
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.
Adds and removes users from the groups specified by group_name on the palyer specified by player_id. The two parameters, to_add and to_remove should be JSON arrays containing the
users to add and remove repsectively from the group.
In all the methods below, if the player exists but is currently inactive, a 404 response with the X-Udj-Missing-Resource header set to player and the X-Udj-Missing-Reason header set to inactive.
The initial participate method must be called by the user before any other methods on the player are called. The only exception to this is the owner of the player. It is assumed that if the player is currently active, the owner is participating. Note that admins must still call the initial participate method. If this method is not called, all other method calls will return a 401 response with the WWW-Authenticate header set to begin-participating.
If the user ceases interaction with the server for a certain period of time, the server MAY consider the user as no longer participating. Interaction is considered calling any of the player interactoin methods below. If the server decides to consider the user as no long participating, the user must call the initial participate method again before it can continue interaction with the player (otherwise all other palyer interaction methods will return a 401 response with the WWW-Autenticate header set to begin-participating).
At any point during participation, the user may be kicked from the player. The user must call the initial participate method again before it can continue interaction with the player (otherwise all other palyer interaction methods will return a 401 response with the WWW-Autenticate header set to kicked).
This method allows the user specified to start participating with the player specified by player_id. If the player requires a password, The request body should have the following JSON in it:
{
'password' : 'password for player'
}
If successful, the server returns a 201 response. If the player requires a password and none was sent, a 401 response will be returned with the WWW-Authenticate set to player-password.
Server's are also allowed to limit the number of participants in a given player. If the current player is full, an Http 403 response will be returned with the X-Udj-Forbidden-Reason set to player-full.
If ther user has been banned from the player, an Http 403 response with the header X-Udj-Forbidden-Reason set to banned will be returned. If the owner attemps to call this method on their own
player an Http 400 response will be returned. If the JSON provided is invalid for any reason this method will return an Http 400 response. If JSON is provided but the content-type
header is not set to text/json and Http 415 response will be returned.
This method informs the server that the calling user is no longer participating with the player. The client SHOULD call this method when they're done participating. If the user was never particiapting in the first place, an Http 404 response is returned with the X-Udj-Missing-Resource header set to user. If the owner attemps to call this method on their own player an Http 400 response will be returned
Returns a JSON array of User objects corresponding to all of the users who are currently participating with the player identified by player_id.
Retrieves a JSON Array of User objects representing the admins for the given player.
Gets a JSON Array of Song Set JSON Objects on the player. If the player has no song sets an empty JSON Array will be returned.
[GET] /udj/0_7/players/player_id/available_music?query=query{&max_results=maximum_number_of_results}
Get the available music for an player that matches the specified query and returns a JSON array of Library Entry objects. An optional maximum number of results can also specified but setting the max_results parameter. The query parameter may not be empty. If it is, a 400 response is returned.
Gets a JSON Array of strings containing all the artists on a given player. The Content-Range header field may be used to restrict the range of responses retrieved from the server.
Gets a JSON Array of LibraryEntry JSON objects corresponding to all the songs that the player has which are by the artist specified by artist_name. May return an empty array if the player has not songs by the given artist.
Get's a JSON Array of Played Active Playlist Entry objects that have been recently played. They are sorted with the song most recently played being at the beginning of the list and the song least recently played at the end of the list. The client may specify the maximum number of Played Active Playlist Entry objects it would like to receive with the max_songs parameter. The server reserves the right to arbitrarily cap the maximum number of results it returns.
Get a random set of songs from the set of available music on the player specified by player_id. A JSON array of Library Entry objects is returned. The number of Library Entry objects returned will be some default value set on the server, but can also be specified using the max_randoms parameter. This parameter will ensure no more than number_desired results are returned. That said, the server may return less than number_desired. number_desired must not be 0. If it is, a 400 response is returned.
For example, if a client wished to retrieve no more than 20 random songs from a player with a player_id of 3, they would use the following URI:
/udj/0_7/players/3/available_music/random_songs?number_of_randoms=20
The server may also reserves the right to arbitrarily cap the maximum number of random songs it will return. However, this cap may not be any lower than 20.
Sets the currently playing song to the song specified by the id and library_id parameter. This method can only be run by the owner of the player or a player admin (otherwise an Http 403 response is returned). If the lib_id parameter is not specified, a 400 response is returned. If the specified lib_id is not currently on the playlist, a 404 response is returned with the X-Udj-Missing-Resource header set to song. Note that if an admin calls this method but is not active, an Http 401 response will be returned with the WWW-Authenticate header set to begin-participating
Informs the server the the currently playing song has finished playing. This method can only be run by the owner of the player or a player admin (otherwise an Http 403 response is returned). If no song is currently playing, a 404 response is returned with the X-Udj-Missing-Resource header set to song. Note that if an admin calls this method but is not active, an Http 401 response will be returned with the WWW-Authenticate header set to begin-participating
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. The user_priority for each
Active Playlist Entry is the priority of that song for the user making the call to this method.
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.
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. If successful this method returns a 201 response. 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 and a 200 response is returned. If the player does not have a song corresponding to the given idavailable a 404 response is returned with theX-Udj-Missing-Resourceheader set tosong. If the player does not have a library with given library_ida 404 response is returned with theX-Udj-Missing-Resourceheader set tolibrary`.
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. May only be called by the player owner or player admin (otherwise an Http 403 response is returned). If the song specified by the id and library_id is not on the playlist, a 404 is returned with the X-Udj-Missing-Resource header set to the value song.
Modifies the active playlist associated with the player specified by player_id. The post must include two parameters, to_add and to_remove. to_add should be a JSON array of Simple Library Entry JSON objects that should be added to the active playlist. to_remove should be an JSON Array of Simple Library Entry JSON objects which correspond to library entries which should be removed from the playlist. At least one parameters must be specified (otherwise an Http 400 response is returned). If successful this method returns a 200 response. 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.
If any of the library entry ids to be removed or added can not be found, a 404 response is returned with the X-Udj-Missing-Resource header set to song along with a JSON array of all the Simple Library Entry JSON objects that couldn't be found. If the JSON given is malformed, a 400 response is returned. If the to_remove parameter is not an empty JSON Array and the calling user is not the player owner or a player admin, this method will return an Http 403 response. In any of these error cases, no changes to the active playlist are made.
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 up voted is then down voted, the initial up vote is removed. If the song specified by id and library_id is not on the playlist a 404 is returned with the X-Udj-Missing-Resource header set to the value song.
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 down voted is then up voted, the initial down vote is removed. If the song specified by id and library_id is not on the playlist a 404 is returned with the X-Udj-Missing-Resource header set to the value song.
Updates the priority of the song to the value specified by the priority post parameter. Higher priorities indicate that the user wants to hear the song sooner. Lower priorities indicate the opposite.
Priorities are relative to one another and used only for ordinal pruposes. They must be a number between 0 and 65,535.
Adds the song specified by id in the library specified by library_id on the player specified by player_id to a user's list of favorite songs. If the player specified by player_id does not exist an Http 404 Response is returned with the X-Udj-Missing-Resource header set to player. If the library specified by library_id does not exists for the specified player then an Http 404 response is returned with the X-Udj-Missing-Resource header set to library If the song specified by id does not exist in the given library an Http 404 Response is returned with the X-Udj-Missing-Resource header set to song.
Removes the song specified by id in the library specified by library_id on the player specified by player_id from a user's list of favorite songs. If the player specified by player_id does not exist an Http 404 Response is returned with the X-Udj-Missing-Resource header set to player. If the library specified by library_id does not exists for the specified player then an Http 404 response is returned with the X-Udj-Missing-Resource header set to library If the song specified by id does not exist in the given library an Http 404 Response is returned with the X-Udj-Missing-Resource header set to song.
Retrieves a JSON Array of Library Entry JSON objects representing songs the user has indicated are their favorites on the player specified by player_id. If the user has no songs indicated as favorites for the player specified by player_id, an empty JSON Array is returned.
These methods may only be called by the owner of a player or one of the player's admins (other wise and http 403 response is returned).
Bans the song specified by id in the library specified by library_id on the player specified by player_id from being played. If no song with that id is found a 404 response is returned with the X-Udj-Missing-Resource header set to song. If no library with the id specified by library_id for the player is found an Http 404 response is returned with the X-Udj-Missing-Resource header set to library.
Removes the ban on the song specified by id in the library specified by library_id on the player specified by player_id from being played. If no song with that id is found a 404 response is returned with the X-Udj-Missing-Resource header set to song. If no library with the id specified by library_id for the player is found an Http 404 response is returned with the X-Udj-Missing-Resource header set to library.
Takes two POST parameters: to_ban and to_unban. Both should be a JSON Array of Simple Library Entry JSON objects that should be banned and unbanded respectively. At least one parameter must be specified (if they are not an Http 400 response is returned). If any of the songs specified in to_ban or to_unban do not exists this method will fail, no changes will be made, and a 404 response with a JSON array of the unknown Simple Library Entry JSON objects will be returned with the X-Udj-Missing-Resource header set to song. If any of the songs specified in to_ban or to_unban have libraries that do not exist for the player this method will fail, no changes will be made, and a 404 response with a JSON array of the unknown Simple Library Entry JSON objects will be returned with the X-Udj-Missing-Resource header set to library.
All of the methods in this section may only be called by the owner of the specified song set, the owner of the player, or one of the player's admins (otherwise an Http 403 response is returned). If the player has disabled the ability for ordinary users to create/modify songsets then calling any of the methods below will result in an Http 403 response. In any of the methods below if the specified player does not exists an Http 404 response is returned with the X-Udj-Missing-Resource set to player.
Creeats a new song set for the player specified by player_id. This method should be given the following JSON:
{
"name" : name of song set,
"description" : a short description of the song set
"date_created" : a timestamp indicating when the song set was created
}
If succesfull this method returns an Http 201. If the content-type header is not set to text/json this method will return an Http 415 Response. If the player already has a song set with given name and different descriptions and/or date_created an Http 409 response will be returned. If any of the name, description, or date_created parameters are missing or the JSON is improperly formatted an Http 400 response will be returned. In order for non-admin/non-owner users to call this method the following conditions must be true:
- The Player is currently Active
- The User is currently participating with the player
If neither one or both of these conditions are not true an Http 403 response is returned. Note that as described above the player must also be currently allowing non-admin/non-owner users to create/modify song sets (otherwise an Http 403 response is returned).
Delets the song set specified by song_set_name for the player specified by player_id. If a song set with the specified name does not exist an Http 404 response is returned with the X-Udj-Missing-Resource header set to song-set.
Adds the song specified by id in the library specified by library_id to the song set specified by song_set_name on the player specified by player_id. If a song set with the specified name does not exist an Http 404 response is returned with the X-Udj-Missing-Resource header set to song_set. If the specified song does not exists an Http 404 response is returned with the X-Udj-Missing-Resource header set to song. If the specified library does not exist for the player an Http 404 response is returned with the X-Udj-Missing-Resource header set to library.
Deletes the song specified by id in the library specified by library_id from the song set specified by song_set_name on the player specified by player_id. If a song set with the specified name does not exist an Http 404 response is returned with the X-Udj-Missing-Resource header set to song_set. If the specified song does not exists an Http 404 response is returned with the X-Udj-Missing-Resource header set to song. If the specified library does not exist for the player an Http 404 response is returned with the X-Udj-Missing-Resource header set to library
Modifies the songs set specified by song_set_name for the player specified by player_id. This method requires two parameters, to_add and to_remove. Both parameters should be JSON Arrays of Simple Library Entry JSON objects to be added and removed respectively. At least one parameter must be specified (otherwise an Http 400 response is returned). If any of the specified songs do not exists an Http 404 response is returned with the X-Udj-Missing-Resource header set to song. If any of the specified libraries do not exist for the player an Http 404 response is returned with the X-Udj-Missing-Resource header set to library.
Set the description of the song set specified by song_set_name for the player specified by player_id to the value specified by the description POST parameter. If a song set with the specified name does not exist an Http 404 response is returned with the X-Udj-Missing-Resource header set to song-set.
Libraries have two permissions, read and write. Read persmissions allow the calling user to query the library and associate it with a player. Write permissions allow the calling user to
modify the contents of the library and modify it's permissions. These permissions may take on one of the following levels:
- None: permission is restricted completly.
- Owner: permission is restricted to only the owner of the library.
- Admin: permission is restricted to only the owner and admins of the library.
- User: permission is restricted to only the owner, admin, and any associated users. (there are two seperate lists of associated users; one for users who can read, and one for users who can write).
- Public: permission is not restricted at all.
Returns a JSON Array of Library JSON objects reprsenting all of the libraries owned by the calling user.
Returns a JSON Array of Library JSON objects reprsenting all of the libraries to which the calling user has at least read access.
Returns a JSON Array of Library JSON objects reprsenting all of the enabled libraries associated with the given player.
Creates a new library owned by the calling user. The put should contain:
{
"name": name of library,
"descirption" : description of library,
"public_key" : The 2048 bit RSA public key for the library
}
The created library object is returned. The library is enabled by default.
Deletes the library specified by library_id for the player specified by player_id (consequently this disables it on any players it is currently enabled on).
The calling user must have write access on the library otherwise an Http 403 response will be returned.
Takes the value of the public_key parameter and sets the libraries public key to the given value.
The calling user must have write access on the library otherwise an Http 403 response will be returned.
Retreives JSON array of users associated with the library specified by library_id are admins of the library. The calling user must have write access on the library otherwise an Http 403 response is returned.
Adds the user specified by user_id to the list of admins for the library specified by library_id. The calling user must have write access on the library otherwise an Http 403 response is returned.
Removes the user specified by user_id from the list admins for the library specified by library_id. The calling user must have write access on the library otherwise an Http 403 response is returned.
Takes two parameters to_add and to_remove. They should each be JSON Arrays of user ids to be added and removed from the list of admins for the library specified by library_id.
The calling user must have write access on the library otherwise an Http 403 response is returned.
Sets the permissions for read and write the the levels specified by the read and write parameter values. The calling user must have write access on the library otherwise an Http 403 response is
returned.
In order to call this method the calling user must have write permission on library otherwise an Http 403 respons is returned.
Takes a JSON Array of JSON Library Entry objects and adds them to the library specified by library_id on the player specified by player_id. If called successfully a 201 response will be returned.
Note the content-type header must be set to text/json, otherwise a 415 response will be returned. If the JSON is malformed a 400 response will be returned. IDs should be unique among all songs for a given player (not including songs that have been deleted). If a request is sent containing a song id the server already knows about with different song information, a 409 response is returned along with the a JSON array containing the conflicting ids.
Example JSON sent by client:
[
{
"id" : "50"
"title" : "Graduate",
"artist" : "Third Eye Blind",
"album" : "Third Eye Blind",
"genre" : "Rock",
"track" : 5,
"duration" : 189
}
]
In order to call this method the calling user must have write permission on library otherwise an Http 403 respons is returned.
Deletes the library entry specified by lib_id from the library specified by library_id on the player specified by player_id for the user specified by user_id. If no song with that lib_id is found a 404 response is returned with the X-Udj-Missing-Resource header set to song. If the song to be deleted is currently queued in the active playlist for the given player, it will be removed from the playlist. If this player is se
In order to call this method the calling user must have write permission on library otherwise an Http 403 respons is returned.
Modifies the library specified by library_id and associated with the player specified by player_id. The post must include two parameters, to_add and to_delete. to_add should be a JSON array of LibraryEntry JSON objects that should be added to the library. to_delete should be an JSON array of library ids which correspond to library entries which should be deleted. At least one parameter must be specified (otherwise an Http 400 resposne is returned). If successful this method returns a 200 response. If any of the songs to be deleted are currently queued in the active playlist for the given player, they will be removed from the playlist.
If any one of the LibraryEntry JSON objects has an id already in use for that player but with different song data, a 409 response is returned. The body of the 409 response contains a JSON array of ids that were given to the server, but the server already has library entries for. If any one of the library entry ids to be deleted can not be found, a 404 response is returned with the X-Udj-Missing-Resource header set to song. If the JSON given is malformed, a 400 response is returned. In any of these error cases for this method, no modification the library's contents is made on the server.
Note these lists are only relevant when the read and/or write permission levels are set to users.
Retreives JSON array of users associated with the library specified by library_id who can read from the library. The calling user must have read access on the library otherwise an Http 403 response is returned.
Adds the user specified by user_id to the list of users with read permission for the library specified by library_id. The calling user must have write access on the library otherwise an Http 403 response is returned.
Removes the user specified by user_id from the list of users with read permission for the library specified by library_id. The calling user must have write access on the library otherwise an Http 403 response is returned.
Takes two parameters to_add and to_remove. They should each be JSON Arrays of user ids to be added and removed from the list of users with read permission for the library specified by library_id.
The calling user must have write access on the library otherwise an Http 403 response is returned.
Retreives JSON array of users associated with the library specified by library_id who can write from the library. The calling user must have write access on the library otherwise an Http 403 response is returned.
Adds the user specified by user_id to the list of users with write permission for the library specified by library_id. The calling user must have write access on the library otherwise an Http 403 response is returned.
Removes the user specified by user_id from the list of users with write permission for the library specified by library_id. The calling user must have write access on the library otherwise an Http 403 response is returned.
Takes two parameters to_add and to_remove. They should each be JSON Arrays of user ids to be added and removed from the list of users with write permission for the library specified by library_id.
The calling user must have write access on the library otherwise an Http 403 response is returned.
Access tokens can be used for libraries to validate that communication coming from any unknown source is indeed allowed communication. If a client wishes to interact with a library, they can obtain a read or write access token. Then any communication they do with the library can be validated by the library by examining the access token provided by the client. The library does this by querying the server as to whether or not the provided access token is valid.
Provides the calling user with a read access token for the library if they have permission to read from the specified library. An Http 403 is returned otherwise.
Provides the calling user with a write access token for the library if they have permission to write to the specified library. An Http 403 is returned otherwise.
Returns a JSON true value if the read access token is valid for the given library. May only be called by owners and admin.
Returns a JSON true value if the read access token is valid for the given library. May only be called by owners and admin.
Creates a new event from the given JSON and returns an Event JSON object representing the created event.
Example input:
{
"name" : name of event,
"player_id" : id of player which will be used for the event,
"start_time" : time the event starts,
"end_time" : time the event ends
"hosts" : JSON array of user id's representing the hosts of the event.
}
Caller must have create even permission for player. Hosts must all have host even permissions. Returns an event id.
Change the event specified by event_id to have the start time specified by the start_time POST parameter.
Change the event specified by event_id to have the end time specified by the end_time POST parameter.
Should contain a single post parameter hosts which is JSON array of hosts for the event. Caller must have modify event permissions and hosts
must all have event host permissions.