-
Notifications
You must be signed in to change notification settings - Fork 1
UDJ REST API 0.6
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,
"admins" : a JSON Array of User JSON Objects who are player admins,
"songset_user_permission" : A boolean indicating whether or not non-admin or non-owner users are allowed to create/modify song sets
"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).
"external_libraries" : A JSON Array of External Library JSON Objects
}
{
"id" : id of library entry (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)
}
{
"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
}
{
"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
}
{
"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)
}
{
"id" : id of external library (string),
"name" : name of external library (string),
"description" : short description of external library (string)
"namespace" : The namespace prefix that will be used when identifying library entries from this external library (string)
}
Library Entry id's may contain a special namespace identifier before any actual id. These namespaces are intended to be used when identifying Library Entry's from external libraries, such that player clients may differentiate between songs from different external libraries as well as from songs in their own internal library. For instance, if a server supports the Rdio external library with the namespace of rdio, then all library entries in the Rdio library will have id's prefixed with the rdio:// namespace. For example, a song in the Rdio library with the id 4klisierd0033l would have a Library Entry id of rdio://4klisierd0033l.
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 a JSON Array of available playlist sorting algorithms JSON Objects.
Retrieves a JSON Array of available external library 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.
These methods may only be called by the owner of the player or a player admin. In any of the methods in this section are called with a player_id that does not exist, a 404 response will be returned with the X-Udj-Missing-Resource header set to player.
Changes whether or not non-admin or non-owner users for the player specified by player_id can create/modify song sets. The songset_user_permission POST parameter must be included and should be set to either yes or no. If some other value for the songset_user_permission is given an Http 400 response will be returned with the response Invalid permission value.
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.
Adds an external library to the list of accessible external libraries for this player. external_library_id should be the id of the external library to add. If no external library with the specified external_library_id exists on the server an Http 404 response will be returned with X-Udj-Missing-Resource header set to external-library.
Removes an external library from the list of accessible external libraries for this player. external_library_id should be the id of the external library to remove. If no such external_library is set as accessible for the given player an Http 404 response will be returned with X-Udj-Missing-Resource header set to external-library.
Adds the user specified by user_id to the set of admins for the player specified by player_id. Upon successfully adding the user as an admin, 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.
Removes the user specified by user_id from the set of admins for the player specified by player_id. If no such user is an admin an Http 404 response is returned with the X-Udj-Missing-Resource header set to user.
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.
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_6/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_6/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 lib_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.
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 lib_id to the active playlist. If successful this method returns a 201 response. If the given lib_id 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 lib_id available a 404 response is returned with the X-Udj-Missing-Resource header set to song
Deletes the given playlist entry from the active playlist. May only be called by the player owner or player admin (otherwise an Http 403 response is returned). If the song specified by the lib_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 ids of library entries that should be added to the active playlist. to_remove should be an JSON array of library ids 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 song ids in the list of songs to be added is already on the playlist, the server will upvote them on the users behalf. 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 ids 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 lib_id parameter on the active playlist. 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 lib_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 lib_id parameter on the active playlist. 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 voted is then up voted, the initial down vote is removed. If the song specified by the lib_id is not on the playlist a 404 with the X-Udj-Missing-Resource header set to song.
Adds the song specified by lib_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 song specified by lib_id does not exist an Http 404 Response is returned with the X-Udj-Missing-Resource header set to song.
Removes the song specified by lib_id on the player specified by player_id to a user's list of favorite songs. If the song specified by lib_id and player_id does not exist 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 specified by user_id 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 lib_id on the player specified by player_id for the user user_id from being played. If no song with that lib_id is found a 404 response is returned with the X-Udj-Missing-Resource header set to song.
Removes the ban on the song identified by lib_id for the player specified by player_id for the user user_id. If no banned song with that lib_id is found a 404 response is returned with the X-Udj-Missing-Resource header set to song.
Takes two POST parameters: to_ban and to_unban. Both should be a JSON Array of library id's 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 this method will fail, no changes will be made, and a 404 response with a JSON array of the unknonwn songs ids will be returned with the X-Udj-Missing-Resource header set to song.
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 lib_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.
Deletes the song specified by lib_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.
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 library id's to be added and removed respectively. At least one parameter must be specified (otherwise an Http 400 response is returned)
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.
If the player attempts to modify a library entry in an external library and the calling user does not have permission to modify that external library, all of these methods will return an Http 403 response. Otherwise, only the player owner and player admins may call these methods (or an Http 403 response will be returned).
Takes a JSON Array of JSON Library Entry object and adds them to the server. 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
}
]
Deletes the library entry specified by lib_id from the library of 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
Modifies the library 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.