Skip to content

0.7 Libraries

Jump to bottom
murph edited this page Mar 10, 2013 · 3 revisions

Libraries

Libraries represent a given collection of songs. Libraries have two permissions, read and write. Read persmissions allow the calling user to query the library, retrieve music from it, and associate it with a player. Write permissions allow the calling user to modify the contents of the library and modify it's permissions. These permissions may take on one of the following levels:

  • None: permission is restricted completely.
  • Owner: permission is restricted to only the owner of the library.
  • User: permission is restricted to only the owner, admin, and any associated users. (there are two seperate lists of associated users; one for users who can read, and one for users who can write).
  • Public: permission is not restricted at all.

Endpoints:

/libraries

GET

Returns a JSON Array of Library objecs.

Optional Parameters

  • owner=user_id - Only return libraries owned by this user.
  • readable=user_id - Only return libraries that this user has permission to read

PUT

Creates a new library owned by the calling user. The put should contain:

{
  "name": name of library,
  "description" : description of library,
  "public_key" : The 2048 bit RSA public key for the library
}

The created library object is returned. The library is enabled by default.

/libraries/library_id

GET

Requires read permission

Returns the specified Library.

DELETE

Requires write permission (or HTTP 403)

Removes the specified Library.

POST

Requires write permission (or HTTP 403)

Modifies the Library.

Content Modification

/libraries/library_id/songs

PUT

Requires write permission (or HTTP 403)

Takes a JSON Array of Library Entries and adds them to the specified library. Upon success, a 201 response will be returned.

Errors

  • HTTP 400 - Bad Request - Your JSON was malformed
  • HTTP 409 - Conflict - The request contains a song id that the server already knows about with different song information. Returns a JSON array containing the conflicting ids.
  • HTTP 415 - Unexpected Media Type - You must set the content-type to 'text/json'.

Example JSON sent by client:

[
  {
    "id" : "50"
    "title" : "Graduate",
    "artist" : "Third Eye Blind",
    "album" : "Third Eye Blind",
    "genre" : "Rock",
    "track" : 5,
    "duration" : 189
  }
]

POST

Requires write permission (or HTTP 403)

Required Parameters

  • to_add - A JSON Array of Library Entries that should be added to the library.
  • to_delete - A JSON Array of Library Entries that should be removed from the library.

Errors

On any error, no changes to the library are made.

  • HTTP 400 - Bad Request - You didn't specify at least one of {to_add | to_delete}
  • HTTP 400 - Bad Request - Malformed JSON
  • HTTP 404 - Not Found - One or more of the library entry ids to be deleted was not found. The X-Udj-Missing-Resource header will be set to song.
  • HTTP 409 - Conflict - The request contains a song id that the server already knows about with different song information. Returns a JSON array containing the conflicting ids.

If successful this method returns a 200 response. If any of the songs to be deleted are currently queued in the active playlist a player, they will be removed from that playlist.

/libraries/library_id/songs/id

DELETE

Requires write permission (or HTTP 403)

Deletes the library entry specified by id from the library. If the song to be deleted is currently queued in an active playlist, it will be removed from there as well.

Errors

  • HTTP 404 - Not Found - No song with that id found. The X-Udj-Missing-Resource header will be set to song.

Read/Write User lists

Note: these lists are only relevant when the read and/or write permission levels are set to users.

/libraries/library_id/read_users

A list of user ID's that can read from the library.

Follows List Semantics

/libraries/library_id/write_users

A list of user ID's that can write to the library.

Follows List Semantics

Library Access Tokens

Access tokens can be used for libraries to validate that communication coming from any unknown source is indeed allowed communication. If a client wishes to interact with a library, they can obtain a read or write access token. Then any communication they do with the library can be validated by the library by examining the access token provided by the client. The library does this by querying the server as to whether or not the provided access token is valid.

/libraries/library_id/read_access_token

GET

Requires READ permission (or HTTP 403)

Provides the calling user with a read access token for the library.

/libraries/library_id/write_access_token

GET

Requires write permission (or HTTP 403)

Provides the calling user with a write access token for the library.

/libraries/library_id/check_token

POST

Required Parameter: token Returns one of {read, write, none}, depending on the token's access level.

Clone this wiki locally