Adding Songs To The Active Playlist

The Active Playlist is a super volatile entity. We've put a lot of thought into how go about interacting with it in order to make sure nothing get's out of sync. Below is a detailed procedure on how clients may add songs to the active playlist in a safe manner.

1. Determine the lib_id of the song you want to add to the active playlist. This will most likely be done by searching the available songs and picking an id from there.
2. Generate a unique client_request_id. This id will be used to identify the request you're about to make for adding this song. How you generate this id is completely up to you. Just make sure you keep track of them so that you never get duplicates. Note that each client_request_id only needs to be unique on a "per-event-per-user" basis. That means clients in the same event may use identical client_request_ids and clients may reuse client_request_ids from old events they're no longer logged into. In other words, the combination of user_id, event_id, and client_request_id should always be unique.
3. Send your add request to the server. It will unconditionally be added to the playlist on the server and will also be given a single upvote by the user making the request.
4. When the server responds with an Http 201 response, you know that you're song has been successfully added to the active playlist.

A Few notes:

1. To actually see the result of adding the song to the playlist, you're going to need to get the whole playlist again by making the api call to get the active playlist.
2. Note that even though your song was added to the playlist, when you requery to get the whole playlist again it may not actually be on the playlist. THIS IS COMPLETELY VALID BEHAVIOR. There are actually a couple reasons why it might not be on there. First, in the time between you adding the song and you getting the new playlist the song may have gone all the way to the top of the playlist and actually played. Therefore, it's no longer on the playlist. Second, between the time you make your add request and query for the new playlist, the song may have been removed from the playlist by the event host (or some other authorized user perhaps).
3. If when making an add request to the server your request times out, that's totally cool. Just send the exact same request again. This is why you have to sent the client_request_id. It's so the server can determine if you've already made that request and not do a duplicate add to the playlist. In fact, if the server did add the song to the playlist and just never got back to you the first time, on this second request it will respond just as if this were your first attempt to add the song and everything went fine.