Skip to content

0.7 Libraries

Jump to bottom
Kurtis edited this page Jul 19, 2013 · 25 revisions

Back to 0.7 API

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, 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 objects.

This call supports Paging Semantics with a default max_results of 100.

Optional Parameters

  • owner=user_id - Only return libraries owned by this user.
  • name=name - Only return libraries with names smililar to the value of this parameter.
  • is_readable=true - Only return libraries that are readable by the calling user.
  • is_official=true - Only return official libraries

Success - HTTP 200:

A list of libraries is returned.

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
}

Success - HTTP 201:

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

/libraries/library_id

GET

Get's information about a specific library.

Success - Http 200:

Returns the specified Library.

Error

  • HTTP 404 - Not Found - Header "X-Udj-Missing-Resource" set to library - There was no library found with the corresponding id.

DELETE

Requires write permission (or HTTP 403)

Deletes the library specified by the given library_id. When deleting a Library, all of it's associated Library Entries are also deleted. The library will also be disabled on any player that has the library currently enabled.

Success - Http 200

Library is now deleted.

Error

  • HTTP 404 - Not Found - Header "X-Udj-Missing-Resource" set to library - There was no library found with the corresponding id.

Partial POST

Requires write permission (or HTTP 403)

If you want to modify any of the fields in the Library you do this by performing a partial POST on the object.

A partial post involves creating a JSON object with only the fields you wish to change. The fields available for change are:

  • name
  • description
  • pub_key

For example, to change the Library's name and description you would send this JSON Object via a POST:

{
  "name" : "new library name"
  "description" : "new library description"
}

Success - Http 200

Library is now modified

Error

  • HTTP 400 - Bad Request - Returned when bad JSON is sent
  • HTTP 404 - Not Found - Header "X-Udj-Missing-Resource" set to library - There was no library found with the corresponding id.
  • HTTP 415 - Unexpected Media Type - You must set the content-type to 'text/json'.

Content Modification

/libraries/library_id/songs

PUT

Requires write permission (or HTTP 403)

Takes a LibraryEntry JSON object and adds it to the specified library.

Success - Http 201

Song is added to the library.

Errors

  • HTTP 400 - Bad Request - Your JSON was malformed
  • HTTP 404 - Not Found - Header X-Udj-Missing-Resource set to library - There was no library found with the corresponding id.
  • HTTP 409 - Conflict - The request contains a song id that the server already knows about with different song information.
  • 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)

JSON object

{
  "to_add" : A JSON Array of [Library Entries](0.7-JSON-Data-Structures#wiki-library-entry) that should be added to the library.
  "to_delete" : A JSON Array of [Simple Library Entries](0.7-JSON-Data-Structures#wiki-simple-library-entry) that should be removed from the library. 
}

Success - HTTP 200

The appropriate songs are added and deleted 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.

Success - HTTP 200

Song is deleted from the library

Errors

  • HTTP 404 - Not Found - Header X-Udj-Missing-Resource set to library - There was no library found with the corresponding id.
  • HTTP 404 - Not Found - Header X-Udj-Missing-Resource header will be set to song. No song with that id found.

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. Note that getting this list requires the READ permission and modifying it requires the WRITE permission.

Follows List-Semantics

/libraries/library_id/write_users

A list of user ID's that can write to the library. Note that getting this list requires the READ permission and modifying it requires the WRITE permission.

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

GET

Checks the validity of the token.

Parameters

  • type - Should either be read or write
  • token - The token to check

Returns a JSON object of the following structure:

{
  "valid" : True or False
}
Clone this wiki locally