Repository navigation
UDJ REST API 0.2
This page serves as documentation for the REST API that will be used by UDJ. All clients and the server should conform to this API.
#JSON Data Structures
{
"id" : unique event id
"name": name of event
"host_id" : id of the user who is the host
"latitude" : the latitude of the event
"longitude" : the longitude of the event
}
{
"id" : id of the user
"first_name" : first name of user
"last_name" : last name of user
}
{
"id" : id of playlist entry on server
"priority" : The priority of the song in the playlist. Allows us to be agnostic of ranking algorithm the server is using
"lib_song_id" : id of the library entry on the server this playlist entry represents
"song" : title of the song
"artist" : song's artist
"album" : song's album
"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
}
{
"id" : id of library entry
"song" : name of the song
"artist" : name of the artist
"album" : name of album
}
{
"lib_song_id" : id of the library entry on the server this playlist entry represents
"song" : title of the song
"artist" : song's artist
"album" : song's album
"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
}
Methods are presented in the following form: [METHOD_TYPE] uri/to/method. All timestamps must be formatted as unix timestamps. {prefix} in a URI is the name of the server. Right now for the official UDJ server, it wil be something like https://www.bazaarsolutions.com:4897/udj.
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. All subsequent requests must be sent with this ticket in the header like so:
X-Udj-Ticket-Hash: ticket that was assigned
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 403 response will be returned. If any of the methods below are called with an invalid ticket in the header, an HTTP 403 response will be returned.
Also returned in the header will be the users given id. This may be required for some future requests. The header field will look like so:
X-Udj-User-Id : user's id
If the credentials provided to this method are invalid, this method will return an HTTP 403 response.
Also included in the header for this request and this request only should be an udj_api_version field, used to specify to which version of the api the client is conforming. If the server does not support the specified api version an HTTP 501/Not Implemented response is returned. The fieled should be specified thusly:
X-Udj-Api-Version : api version
This method allows a client to retrieve a list of nearby events 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 event objects.
Creates a new event. The user who is associated with the hash that was used in this request is set as the host. This method should be given the following JSON:
{
"name" : name of party
"coords" : {"latitude" : latitude, "longitude": longitude},
"password" : password
}
The coords and password attributes are optional. The host will be automatically "logged in" to the party. This method then returns the id of the party in JSON like so:
{"event_id" : id of event}
Ends the event specified by event_id.
This method allows a client to "login" to a event and thus be able to query it's associated available music and active playlist. event_id should be the id of the event to log into. The user to be logged in is determined by the ticket in the header of the request. If the event requires a password, a password must be supplied in the header like so:
X-Udj-Event-Password : password for event
If for whatever reason logging into the event was unsuccessful, an appropriate HTTP Status code will be set and an error message will be returned. This 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 an HTTP 403 response. If the event_id doesn't exist a 404 response is returned. If the party has ended a 410 response is returned.
Gets all the event goers currently logged into the event specified by event_id. If the event_id doesn't exist a 404 response is returned. If the party has ended a 410 response is returned.
If issued by the user corresponding to user_id this is equivalent to logging out. If issued by anyone else, this is equivalent to "kicking" the user with user_id from the event specified by event_id. If the issuer of this call is otherwise not authorized to delete the specified user_id from the event, an HTTP 403 response will be returned. If the event_id doesn't exist a 404 response is returned. If the party has ended a 410 response is returned.
Get the available music for an event that matches the specified query. An optional maximum number of results can also specified but setting the max_results parameter. If the event_id doesn't exist a 404 response is returned. If the party has ended a 410 response is returned.
For example, if one wanted to search for the Beatles, retrieve no more than 20 results, and do so for the event with a event_id of 3, they would use the following URI:
{prefix}/events/3/available_music/the%20beatles?max_results=20
Get a random set of songs from the set of available music at the event specified by event_id. A JSON array of Library Entries is returned. The number of Library Entries will be some default value, 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. If the event_id doesn't exist a 404 response is returned. If the party has ended a 410 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:
{prefix}/events/3/available_music/random_songs?number_of_randoms=20
Gets the current song that is playing. Returns an Current Song JSONObject. If the event_id doesn't exist a 404 response is returned. If the party has ended a 410 response is returned.
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 the current song to it). This method can only be run by the host of the party.
Stops a event. This may only be issued by the host of the party.
Note that in order to call any of these methods, the issuer of the method must be logged into the appropriate event. Otherwise, an HTTP 403 response will be returned. In any of these methods, if the event_id doesn't exist a 404 response is returned. Also, if the party has ended a 410 response is returned.
Returns a JSON array of Playlist Entry objects for the event specified by event_id. The entire playlist is returned.
Adds songs to the active playlist of the event specified by event_id. This request should include a single JSONArray of ids that correspond to the songs that should be added to the active playlist. This method then returns an array of Active playlist objects that correspond to the songs that were added.
Example JSON sent by client.
[130,5]
Example JSON returned by Server:
[
{
"id" : 10,
"priority" : 1,
"lib_song_id" : 130,
"song" : "10 Day's Late",
"artist" : "Third Eye Blind",
"album" : "Blue",
"up_votes" : 1,
"down_votes" : 0,
"time_added" : 1321019418,
"adder_id" : 5023
},
{
"id" : 11,
"priority" : 1,
"lib_song_id" : 5,
"song" : "D.A.N.C.E.",
"artist" : "Justice",
"album" : "Justice",
"up_votes" : 1,
"down_votes" : 0,
"time_added" : 1321019418,
"adder_id" : 5023
}
]
We need to be able to detect if two different clients add the same song within some certain threshold time and some special behavior should happen in this case. We'll have to hash this out later...
Votes up the song specified by playlist_id on the active_playlist. playlist_id is the id of the playlist entry on the server.
Votes down the song specified by playlist_id on the active_playlist. playlist_id is the id of the playlist entry on the server.
Starts a long poll operation which returns when any change to the active playlist happens.
Takes a JSONArray of Library Entry objects and adds them to the server. The server then returns an array ids which correspond to the songs that were successfully added on the server. Example JSON sent by client:
[
{
"id" : 1
"song" : "Sleep Now In The Fire",
"artist" :"Rage Against The Machine",
"album" : "The Battle Of Los Angeles"
},
{
"id" : 2
"song" : "Graduate",
"artist" : "Third Eye Blind",
"album" : "Third Eye Blind"
}
]
Example JSON returned by server:
[1,2]
If a client sends a two requests that contain objects which have the same id, the second is ignored. The server will still return the appropriate JSONArray.
Deletes all the songs in a given users library. The user is specified by user_id.
Deletes the library entry specified by lib_id from the library of the user specified by user_id. lib_id should be the server id of the library entry.