WaveBox API (August 18th, 2012)

The basics:

Every call to the WaveBox API requires authentication data, e.g. a session ID.  Unless otherwise specified, all other parameters are optional.  Each API call is prefixed by /api/ in the URL.


Authentication

Description:  

Used to create a new session id for an existing user.  The session id returned is used to access all other API calls.

URL:  api/login

Parameters

Name

Description

Required

u

The username of the identity you would like to use to access the API.

p

The password associated with the above username.

Returns

Name

Description

error

An object containing information about any error that may have occurred.  Null if the call is successful.  The structure of the error object is discussed in the Data Structures segment.

sessionId

The session id for this login session

Example:

http://localhost:6500/api/login?u=TestUser&p=TestPassword

Folders

Description:  

Returns information about a folder, including a listing of their available sub-folders and media items, when supplied with a folder ID.  When no folder ID is supplied, information about all top-level folders the WaveBox server knows about is supplied; however, media item information is excluded.

URL:  api/folders

Parameters

Name

Description

Required

id

The ID of the folder you would like information about.  If null, information about all top-level folders known by the server will be retrieved.

s

The sessionId of the active session you would like to use to access the API.

Returns

Name

Description

error

An object containing information about any error that may have occurred.  Null if the call is successful.  The structure of the error object is discussed in the Data Structures segment.

folders

An array of folder objects, which contain information about the folder(s) requested.  The structure of the artist object is discussed in the Data Structures segment.

mediaItems

An array of mediaItem objects, which contain information about the songs in the requested folder.  Empty array if ‘id’ is not specified.  The structure of the song object is discussed in the Data Structures segment.

Example:

http://localhost:6500/api/folders?id=125&s=SESSIONID

Artists

Description:  

Returns information about an artist, including a listing of their available albums and songs, when supplied with an artist ID.  When no artist ID is supplied, information about all artists the WaveBox server knows about is supplied; however, album and song information is excluded.

URL:  api/artists

Parameters

Name

Description

Required

id

The ID of the artist you would like information about.  If null, information about all artists known by the server will be retrieved.

includeSongs

If set to false, or not included, songs array will be empty. Otherwise, songs array will contain all associated songs for this artist.

s

The sessionId of the active session you would like to use to access the API.

Returns

Name

Description

error

An object containing information about any error that may have occurred.  Null if the call is successful.  The structure of the error object is discussed in the Data Structures segment.

artists

An array of artist objects, which contain information about the artist(s) requested.  The structure of the artist object is discussed in the Data Structures segment.

albums

An array of album objects, which contain information about the album(s) requested.  The structure of the album object is discussed in the Data Structures segment.  Null if no artist ID is supplied.

songs

An array of song objects, which contain information about the songs in the requested album.  Empty array if ‘id’ is not specified, includeSongs not specified, or includeSongs is false.  The structure of the song object is discussed in the Data Structures segment.

Example:

http://localhost:6500/api/artists?id=125&s=SESSIONID

Albums

Description:  

Returns information about an album, including the songs that are on that album, when supplied with an album ID.  When no album ID is supplied, information about all albums the WaveBox server knows about is supplied; however, song information is excluded from this listing.

URL:  api/albums

Parameters

Name

Description

Required

id

The ID of the album you would like information about.  If null, information about all albums known by the server will be retrieved.

s

The sessionId of the active session you would like to use to access the API.

Returns

Name

Description

error

An object containing information about any error that may have occurred.  Null if the call is successful.  The structure of the error object is discussed in the Data Structures segment.

albums

An array of album objects, which contain information about the album(s) requested.  The structure of the album object is discussed in the Data Structures segment.

songs

An array of song objects, which contain information about the songs in the requested album.  Null if ‘id’ is not specified.  The structure of the song object is discussed in the Data Structures segment.

Example:

http://localhost:6500/api/albums?id=125&s=SESSIONID

Songs

Description:  

The songs API call returns information about a song, when supplied with a song ID.  When no song ID is supplied, information about all song the WaveBox server knows about is supplied.

URL:  api/artists

Parameters

Name

Description

Required

id

The ID of the song you would like information about.  If null, information about all songs known by the server will be retrieved.

s

The sessionId of the active session you would like to use to access the API.

Returns

Name

Description

error

An object containing information about any error that may have occurred.  Null if the call is successful.  The structure of the error object is discussed in the Data Structures segment.

songs

An array of song objects.  Either contains the song asked for by specifying an id, or contains all songs on the server.  The structure of the song object is discussed in the Data Structures segment.

Example:

http://localhost:6500/api/artists?id=125&s=SESSIONID

Cover Art

Description:  

Returns an image file if one exists for the id supplied.  If no image exists for the supplied id, then an empty body is returned.

URL:  api/cover

Parameters

Name

Description

Required

id

The ID of the item you would like art for.  All IDs are unique, so no item type is required.  The ID may be for a folder, artist, album, song, playlist, podcast, podcast episode

size

The horizontal size of the image you would like to receive.  The aspect ratio will be maintained.  i.e. If an image is 600x500 and you specify size=300, then the resulting image will be 300x250.  If size is not specified, the original image file is returned.

s

The sessionId of the active session you would like to use to access the API.

Returns

Name

Description

HTTP STATUS 404 on error

Returns an HTTP status code 404 file not found on error or no art exists. Otherwise, returns binary art file.

Example:

http://localhost:6500/api/cover?id=125&type=album&s=SESSIONID

Stream

Description:  

Used to retrieve a song or video stream.  May return the original media file or a transcoded file depending on the parameters sent.

URL:  api/artists

Parameters

Name

Description

Required

id

The ID of the media item you would like to stream.  If null, information about all songs known by the server will be retrieved.

transType

The transcoding format. Options include: “MP3”

transQuality

The transcoding quality. Defaults to “Medium”. Options include: “Low”, “Medium”, “High”, “Extreme”, or integer bitrate value.  Word values will produce VBR files while bitrate values will produce CBR files.

s

The sessionId of the active session you would like to use to access the API.

Returns

Name

Description

error (if unsuccessful)

An object containing information about any error that may have occurred.  NO JSON IS RETURNED ON SUCCESS, ONLY BINARY DATA.  The structure of the error object is discussed in the Data Structures segment.

Example:

http://localhost:6500/api/stream?id=125&s=SESSIONID

Jukebox

Description:  

Used to manipulate the jukebox function of WaveBox.  This includes functions such as “play”, “pause”, “stop”, and other related actions.  Can potentially return an error, the status of the jukebox, and the jukebox’s current playlist.

The “playlist”, “add”, “remove”, “move”, and “clear” actions manipulate the jukebox play queue.

     • Add takes only a song ID or list of song IDs

     • Remove takes an index or list of indexes in the jukebox playlist

     • Move takes a from index, to index pair or list of pairs  

        e.g. action=move&index=1,2,5,6 would move the song at index 1 to index 2 and the song at index 5 to index 6.

The “play”, “pause”, “stop”, “prev”, and “next” control the jukebox player.

     • Play takes an index of the jukebox playlist, or if no index and paused or stopped, plays the current index

Note: Songs must be added to the jukebox’s playlist before they can be played.  

URL:  api/jukebox

Parameters

Name

Description

Required

action

The action to be performed, defaults to “status”. Possible values are: “play”, “pause”, “stop”, “prev”, “next”, “status”, “playlist”, “add”, “remove”, “move”, “clear”

id

Only used (and required) with the “add” action. Contains a comma delimited list of song IDs to add to the playlist

(✓)

index

Only used (and required) with actions that modify the playlist such as “add”, “remove”, or “move”.  When using “remove”, may be a comma-delimited list of indexes to remove. When using “move”, this is a comma-delimited pair of indexes with the first being the ‘from’ index and the second being the ‘to’ index.

(✓)

s

The sessionId of the active session you would like to use to access the API.

Returns

Name

Description

error

An object containing information about any error that may have occurred.  Null if the call is successful.  The structure of the error object is discussed in the Data Structures segment.

jukeboxStatus

An object containing information on the jukebox player. The structure is discussed in the Data Structures segment.

jukeboxPlaylist

An object describing the jukebox play queue. The structure is discussed in the Data Structures segment.

Example:

http://localhost:6500/api/jukebox?action=add&songId=125&s=SESSIONID

Scrobble

Description:  

Used to submit Last.fm song plays and submissions.  Can be used to submit multiple offline events.

URL:  api/folders

Parameters

Name

Description

Required

event

A comma-delimited list of id/event/unix-timestamp triplets. All timestamps should be in UTC time zone. Event types include: p for scrobble play, and s for scrobble submission. Example: 10,p,213214621231,1231,s,213214821231,122,s,213214381231,130,p,21321439231

s

The sessionId of the active session you would like to use to access the API.  Scrobbles will be recorded for this user.

Returns

Name

Description

error

An object containing information about any error that may have occurred.  Null if the call is successful.  The structure of the error object is discussed in the Data Structures segment.

Example:

http://localhost:6500/api/folders?id=125&s=SESSIONID

Stats Updating

Description:  

Currently only used to update server play counts.  In the future, additional statistics may be supported.  May be used to submit multiple offline actions.

URL:  api/updateStats

Parameters

Name

Description

Required

event

A comma delimited list of id/unix-timestamp events. All timestamps should be UTC time zone. Example: 10,213214621231,1231,213214821231,122,213214381231,130,21321439231

s

The sessionId of the active session you would like to use to access the API. Stats will be recorded for this user.

Returns

Name

Description

error

An object containing information about any error that may have occurred.  Null if the call is successful.  The structure of the error object is discussed in the Data Structures segment.

Example:

http://localhost:6500/api/folders?id=125&s=SESSIONID

Status

Description:  

Returns the current server status information.  May be used to check if the server is online or for other purposes.

URL:  api/status

Parameters

Name

Description

Required

s

The sessionId of the active session you would like to use to access the API.

Returns

Name

Description

error

An object containing information about any error that may have occurred.  Null if the call is successful.  The structure of the error object is discussed in the Data Structures segment.

status

An object containing server status information.  The structure of the status object is discussed in the Data Structures segment.

Example:

http://localhost:6500/api/status?id=125&s=SESSIONID

Podcasts

Description:  

Returns information about a podcast or an episode, or alternatively performs an action on a podcast or an episode.  If an action is not specified, information will be returned.

URL:  api/podcasts

Parameters

Name

Description

Required

id

The ID of the podcast or episode you are requesting

action

Action you would like to perform.  Possible actions include “add”,  “delete”, or “edit”.  If not specified, information is returned instead of an action being performed.

podcastUrl

The (url encoded) url of the podcast to add. Used with the “add” action only.

podcastKeepCap

The number of episodes to keep for the podcast.  Only used with the “add” and “edit” actions.

s

The sessionId of the active session you would like to use to access the API.

Returns

Name

Description

error

An object containing information about any error that may have occurred.  Null if the call is successful.  The structure of the error object is discussed in the Data Structures segment.

podcasts

An array of podcast objects.  The structure of the podcast object is discussed in the Data Structures segment.

episodes

An array of podcast episode objects.  The structure of the podcast episode object is discussed in the Data Structures segment.

Example:

http://localhost:6500/api/podcasts?id=125&s=SESSIONID

User Management

Description:  

Used to retrieve or update user information.

URL:  api/users

Parameters

Name

Description

Required

id

The ID of the user.

action

Action you would like to perform.  Possible actions include “add”,  “delete”, or “edit”.  If not specified, information is returned instead of an action being performed.  These actions may only be performed by users in the Administrator group.

username

The username of the user to add.  Used with the “add” action only.

password

The password of the user to add or edit.  Only used with the “add” and “edit” actions.

group

The group of the user to add or edit. Only used with the “add” and “edit” actions. Options include: “Administrator”, “Listener”

s

The sessionId of the active session you would like to use to access the API.

Returns

Name

Description

error

An object containing information about any error that may have occurred.  Null if the call is successful.  The structure of the error object is discussed in the Data Structures segment.

user

An object containing user information.  The structure of the user object is discussed in the Data Structures segment.

Example:

http://localhost:6500/api/users?id=125&s=SESSIONID

Settings

Description:  

Returns the settings information, or if keyValue is specified, updates setting(s). The available settings are determined by the calling user’s group.

URL:  api/settings

Parameters

Name

Description

Required

keyValue

Key/value pair(s) for the setting(s) to edit.  Not available yet.

To add or remove from a setting that is a list, such as media folders, use a + or - as the first character of the value to designate an add or remove. Example: mediaFolders,+/path/,mediaFolders,-/path/

s

The sessionId of the active session you would like to use to access the API.

Returns

Name

Description

error

An object containing information about any error that may have occurred.  Null if the call is successful.  The structure of the error object is discussed in the Data Structures segment.

settings

An object containing settings information.  The structure of the user object is discussed in the Data Structures segment.

Example:

http://localhost:6500/api/settings?id=125&s=SESSIONID