-
Notifications
You must be signed in to change notification settings - Fork 17
UDJ REST API 0.5
This page serves as general documentation for the UDJ REST API.
#JSON Data Structures
{
"id" : Id of user,
"username" : User name of the user,
"first_name" : Users first name,
"last_name" : Users last name
}
{
"id" : unique player id,
"name": name of player,
"owner_username" : username of the player owner,
"owner_id" : id of the player owner,
"has_password" : true if the player has a password, false otherwise,
"latitude" : the latitude of the location of the player (optional),
"longitude" : the longitude of the location of the player (optional),
}
{
"id" : id of library entry (should be a positive integer),
"title" : name of the song,
"artist" : name of the artist,
"album" : name of album,
"track" : number of track,
"genre" : genre of the song,
"duration" : duration of song in seconds
}
{
"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,
"adder" : User JSON Object
}
{
"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,
"time_played" : Time the entry started playing,
"adder" : User JSON Object
}
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
All times are in UTC.
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. Unless otherwise revoked, tickets are valid for 24 hours.
If the username and password combination is invalid a 401 response will be returned. The WWW-Authenticate header will be set to password.
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.
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.
Creates a new player. The user specified by user_id is set as the owner of the player. This method should be given the following JSON:
{
"name" : name of player,
"location":{
"address": Address where player is located,
"city": City where player is located,
"state": **Two letter** State Code of State where player is located,
"zipcode": 5 digit zip code where player is located
},
"password" : password
}
The location and password attributes are optional. If successful, a 201 response will be returned with the body set to the following JSON:
{ "player_id" : id of player }
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".
These methods may only be called by the owner of the player. 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 the name of the player specified by player_id to the string specified by the name POST parameter. If the name specified in the body is blank, a 400 response is returned with the body "Bad name". If the name is already in use on another player owned by the user, a 409 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 withe 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 request must have the following parameters: address, city, state, and zipcode. The state parameter should be the two letter code for that state. If the given location can not be found by the server then a 400 response is returned with the body set to 'Bad location'
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.
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.
Also, the initial participate method specified directly below must be successfully called before any of the other methods below may be called for a particular player. If not, any call to the other methods below will result in a 401 response with the WWW-Authenticate header set to the value of begin-participating.
This method allows the user specified by user_id to start participating with the player specified by player_id. If the player requires a password, the X-Udj-Player-Password header must be provided like so:
X-Udj-Player-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.
Returns a JSON array of User objects corresponding to all of the users who are currently participating with the player identified by player_id.
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.
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/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. 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.
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" : Current Song 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 or being played, a 409 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. 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. If a user who is not the owner of the player calls this method, a 403 response is returned.
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. Both parameters must be specified but either one may contain empty JSON arrarys. If successful this method returns a 200 response.
If any of the song ids in the list of songs to be added is already on the playlist, a 409 response is returned along with a JSON array of all the given song ids that are already on the playlist. 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. In any of these error cases, no changes to the active playlist are made.
Only the owner of the player may call this method. Otherwise a 403 response is returned.
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.
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 with a non-unique id, a 409 response is returned.
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.
Modifies the library associated with the player specified by player_id for the user specified by user_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. Both parameters must be specified but either one may contain empty JSON arrarys. 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, 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 all of these error cases, no modification the library's contents is made on the server.
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.