-
Notifications
You must be signed in to change notification settings - Fork 1
UDJ REST API 0.2
This page serves as general documentation for the UDJ REST API.
#JSON Data Structures
{
"id" : unique event id
"name": name of event
"host_id" : id of the user who is the host
"host_username" : username of the event host
"latitude" : the latitude of the event
"longitude" : the longitude of the event
"has_password" : true if the event has a password, false otherwise
}
{
"id" : id of the EventGoer
"username" : username of the EventGoer
"first_name" : first name of EventGoer
"last_name" : last name of EventGoer
"logged_in" : true if the use is logged into the given event, false otherwise
}
{
"id" : id of library entry
"title" : name of the song
"artist" : name of the artist
"album" : name of album
"duration" : duration of song in seconds
}
{
"id" : id of playlist entry on server
"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
}
{
"id" : id of the song when it was on 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. All subsequent requests must be sent with this 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 basis (thus allowing the same user to authenticate from multiple clients on different machines at the same time). There for a ticket hash issued for a particular machine will cause an HTTP 403 response if used on another machine.
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 included in the header for this request and this request only should be an X-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 field should be specified like so:
X-Udj-Api-Version : api version
The response from the server (if authentication is successful) will contain the users given id in the header. 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.
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.
This method allows a client to retrieve a list of all events that have a name similar to the name parameter. A JSON array of Event objects is returned. If no parties are found matching the specified name, an array of length zero will be returned.
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}
If the client has already created an event and not yet ended it, an Http 409 response will be returned and no new event will be created.
Stops an event. This may only be issued by the host of the party. When issued, the list of all available songs for that event may be deleted by the client, server, or both (although the songs them selves must remained untouched).
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_id should be the user attempting to login (note this user_id should match the user associated with the ticket specified in the header, if not a 403 response is returned). 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 and the header X-Udj-Gone-Resource is set to event. If the user has already joined an event which is different from the event they're are trying to join with this request, an Http 409 response is returned along an Event JSON object describing the event in which the user is currently. In order to resolve this conflict, the user must log out of the event they're currently logged into.
Returns a JSON array of EventGoer objects corresponding to all of the users who have logged in to 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 and the header X-Udj-Gone-Resource is set to event. In order to issue this query, the user must currently logged into the given party, otherwise a 403 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.
Takes a JSON array of id's corresponding to songs in the library and adds them to the list of available music. This method may only be executed by the party host. The server returns a JSON array of all the song ids that were given by the client that are now on the list of available music on the server. This method also requires the user to specify the UUID of the machine they are working from via the X-Udj-Machine-UUID header. For more information about the UUID please read the Library Methods section.
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. If the event_id doesn't exist a 404 response is returned. If the party has ended a 410 response is returned and the header X-Udj-Gone-Resource is set to event.
Deletes the song specified by song_id from the available music for the event specified by event_id. This method may only be executed by the party host or other specifically authorized users.
Get a random set of songs from the set of available music at the event specified by event_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. If the event_id doesn't exist a 404 response is returned. If the party has ended a 410 response is returned and the header X-Udj-Gone-Resource is set to event.
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.
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. In any of these methods, if an event has ended a 410 response is returned and the header X-Udj-Gone-Resource is set to event
Returns a JSON Object that 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 songs to the active playlist of the event specified by event_id. This request should include a single JSON array of JSON objects that look like the following:
{ "lib_id" : song to add, "client_request_id" : request id}
Each JSON object has two attributes. lib_id is the id of the song that should be added to the active playlist. add_request_id is a unique id that corresponds to the particular request for the given lib_id to be added. This allows the client to send the same request multiple times should it fail to get a response on the first attempt but the song was actually added on the server. Therefore, client request ids should be unique with respect to a specific client.
When a song is added for the first time, an up vote by the adding user is automatically inserted by the server.
Example JSON sent by client.
[{"lib_id" : 130, "client_request_id" : 1}, {"lib_id" : 5, "client_request_id" : 2}]
Retrieves all of the requests that a particular user has submitted to particular event for adding songs to the active playslist. The response is in the form of a JSON array of JSON objects of the following form:
{"lib_id" : id of song added, "client_request_id" : request id}
Clients may only request their add requests belonging to the specified user. If an attempt is made to obtain the add requests of a user_id not corresponding to the supplied ticket hash, a 403 error returned.
Deletes the given playlist entry from the active playlist. May only be called by the adder of the playlist entry or the event host.
Votes up the song specified by playlist_id on the active playlist. playlist_id is the id of the Active Playlist Entry on the server. It the playlist id doesn't exist on the active playlist, a 404 response is returned. 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 is no longer on the playlist (i.e. it has been played or otherwise removed) an Http 410 repsonse is returned and the header X-Udj-Gone-Resource is set to song.
Votes down the song specified by playlist_id on the active playlist. playlist_id is the id of the Active Playlist Entry on the server. It the playlist id doesn't exist on the active playlist, a 404 response is returned. 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 is no longer on the playlist (i.e. it has been played or otherwise removed) an Http 410 repsonse is returned and the header X-Udj-Gone-Resource is set to song.
Returns a list of all the votes a particular user has issued for songs on the active playlist as is (note that votes for songs no longer on the active playlist will not be included in the response). The user_id and the user associated with the given ticket in the header must match or a 403 response is returned. The JSON returned by this request is a JSON object containing two arrays, one containing all the playlist id's on which the give user has up voted, and another containing a list of playslist id's on which the user has down voted.
Example response:
{ "up_vote_ids" : [4,9,10], "down_vote_ids" : [3,4] }
All library methods must include the header X-Udj-Machine-UUID. The header must specify the UUID corresponding to the machine the method calls are being made from. The UUID for a given machine should always be the same, thus allowing the server to associate specific songs with a particular machine. The UUID should appear in the header as so:
X-Udj-Machine-UUID : 243893920193949a9d9e9f9a9d9394b
Takes a JSON array of Library Entry objects and adds them to the server. The server then returns a JSON array of 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",
"duration" : 205
},
{
"id" : 2
"song" : "Graduate",
"artist" : "Third Eye Blind",
"album" : "Third Eye Blind",
"duration" : 189
}
]
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 JSON array.
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.