Repository navigation
UDJ REST API 0.5
This page serves as general documentation for the UDJ REST API.
#JSON Data Structures
{
"username" : User name of the user,
"first_name" : Users first name,
"last_name" : Users last name
}
{
"id" : unique player id
"name": name of player
"owning_user_id" : id of the user who owns this player
"owner_username" : username of the event host
"latitude" : the latitude of the location of the player
"longitude" : the longitude of the location of the player
"has_password" : true if the event has a password, false otherwise
}
{
"id" : id of library entry,
"title" : name of the song,
"artist" : name of the artist,
"album" : name of album,
"track number" : number of track,
"genre" : genre of the song,
"duration" : duration of song in seconds
}
{
"lib_song_id" : id of the library entry on the server this playlist entry represents,
"title" : title of the song,
"artist" : song's artist,
"album" : song's album,
"duration" : duration of the song in seconds,
"up_votes" : number of up-votes this entry has,
"down_votes" : number of down-votes this entry has,
"time_added" : Time the entry was added,
"adder_id" : user id of user who added the song to the playlist,
"adder_username" : username of the user who added the song to the playlist
}
{
"lib_song_id" : id of the library entry on the server this playlist entry represents,
"title" : title of the song,
"artist" : song's artist,
"album" : song's album,
"duration" : duration of song in seconds,
"up_votes" : number of up-votes this entry has,
"down_votes" : number of down-votes this entry has,
"time_added" : Time the entry was added,
"time_played" : Time the entry started playing,
"adder_id" : user id of user who added the song to the playlist,
"adder_username" : username of the user who added the song to the playlist
}
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 an authentication ticket in the header of the response. If the username and password combination is invalid a 403 response will be returned. All subsequent requests must be sent with the given ticket in the header like so:
X-Udj-Ticket-Hash: ticket that was assigned
Ticket's are issued on a per-user, per-ip address, per-port basis (thus allowing the same user to authenticate from multiple clients on different machines at the same time). Therefore, if a ticket hash issued for a particular user is used on a machine with a different ip and/or port, an HTTP 401 response will be returned. In such a case, the WWW-Authenticate header will be set to the value ticket-hash.
Unless otherwise revoked, tickets are valid for 24 hours. 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. Once again, in either case the WWW-Authenticate header will be set to the value ticket-hash.
The response from the server (if authentication is successful) will contain the users given id in the following form of JSON:
{ "user_id" : id }
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 events (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": State where player is located,
"zipcode": Zip code where player is located
},
"password" : password
}
The location and password attributes are optional. 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 successful, the response to this method will include the unique id assigned to the player. This response will be in JSON and look like the following:
{ "player_id" : id of player }
These methods may only be called by the owner of the player.
Changes the name of the player specified by player_id to the string in the body of the request.
Changes the password of the player specified by player_id to the string in the body of the request.
Removes the password on the player specified by the player_id.
Changes the location of the player specified by player_id to the location specified in the body of the request. The location should be specified using the following JSON form:
{
"address": Address where player is located,
"city": City where player is located,
"state": State where player is located,
"zipcode": Zip code where player is located
}
The content-type header must also be set to text/json. If the content-type header is not set correctly or the JSON does not have the form specified above, a 400 response is returned.
In all the methods below, if the player exists but is currently inactive, a 404 response with the X-Udj-Missing-Resource set to player. The header X-Udj-Missing-Reason will be set to inactive.
Also, the initial participate method must be successfully called before any of the below methods may be called. If not, any call to the 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 event
If the player requires a password and none was sent, a 401 response will be returned with the WWW-Authenticate set to player-password.
This method allows the user specified by user_id to stop participating with the player specified by player_id. It may only be called by the user specified by user_id. A client SHOULD call this method when the client no longer plans to participate with the player.
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 event 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.
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 event with a event_id of 3, they would use the following URI:
/udj/events/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 playlist_entry_id parameter (ergo the song must have been on the active playlist before setting it as the current song). This method can only be run by the host of the party. If the playlist_entry_id is not specified, a 400 response is returned.
Gets the state of the the player. Will either return playing or paused.
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, a 400 response is returned.
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 Current Song 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.
Example JSON response:
{
"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. {}).
Adds the song specified by lib_id to the active playlist. If the given lib_id is already on the playlist, a 409 response is returned.
Deletes the given playlist entry from the active playlist. May only be called by the adder of the song or the player owner. If the song specified by the lib_id is not on the playlist, a 404 is returned with the X-Udj-Resource-Missing header set to the value song.
Votes up the song specified by lib_id 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 the lib_id is not on the playlist a 404 is returned with the X-Udj-Resource-Missing header set to the value song.
Votes down the song specified by lib_id 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 Library Entry object and adds it to the server. Note the content-type header must be set to text/json, otherwise a 415 response will be returned.
Example JSON sent by client:
{
"id" : 50
"song" : "Graduate",
"artist" : "Third Eye Blind",
"album" : "Third Eye Blind",
"genre" : "Rock",
"track number" : 5,
"duration" : 189
}
IDs should be unique among all songs. If a request is sent containing a song with a non-unique id, a 409 response is returned.
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.
Bans the song specified by lib_id on the player specified by player_id for the user user_id from being played.
Removes the ban on the song identified by lib_id for the player specified by player_id for the user user_id.