Ampache's XML API DEVELOPMENT VERSION

Ampache's XML API DEVELOPMENT VERSION

API Versions: {Current Stable (3.5.x)} {Development (3.6.x)}

Compatible Versions: >= 360000

Ampache Provides an API for pulling out it's meta data in the form of simple XML or JSON responses. This was originally created for use by Amarok, but there is no reason it couldn't be used to create other front-ends to the Ampache data. Access to the API is controlled by the Internal Access Control Lists. The KEY defined in the ACL is the passphrase that must be used to establish an API session. Currently all requests are limited to a maximum of 5000 results for performance reasons. To get additional results pass offset as an additional parameter. If you have any questions or requests for this API please submit a Feature Request. All dates in the API calls should be passed as ISO 8601 dates.

Sending Handshake Request

The handshake is a combination of the following three things

Encoded Passphrase
Timestamp
Username

The key that must be passed to Ampache is SHA256(TIME+KEY) where KEY is SHA256('PASSWORD'). Below is a PHP example

$time = time(); 
$key = hash('sha256','mypassword');
$passphrase = hash('sha256',$time . $key);

Once you've generated the encoded POST to the following URL localhost/ampache is the location of your Ampache installation

http://localhost/ampache/server/xml.server.php?action=handshake&auth=$passphrase&timestamp=$time&version=350001&user=vollmerk

If your Password, IP and Username match a row in the Access List the following will be returned.

XML response

<root>
    <auth>AUTHENTICATION TOKEN</auth>
    <version>APIVERSION</version>
    <update>Last Update ISO 8601 Date</update>
    <add>Last Add ISO 8601 Date</add>
    <clean>Last Clean ISO 8601 Date</clean>
    <songs>Total # of Songs</songs>
    <artists>Total # of Artists</artists>
    <albums>Total # of Albums</albums>
    <tags>Total # of Tags</tags>
    <videos>Total # of Videos</videos>
</root>

JSON Response

All future interactions with the Ampache API must include the TOKEN as a get variable named 'AUTH'.

Errors

All errors will be returned as an XML document as specified in the XMLAPI Error Document. When possible the text part of the message will be translated into the users configured language.

Methods

Following REST ideals all Read operations must be GET requests, Write/Updates POST, Deletion DELETES and information gathering OPTIONS. Two operations can have identical URLs the action is differenated by the HTTP method used. For example GET /democratic/song/12039 would return the number of votes in the democratic playlist (and its respective position) for the specified song. DELETE /democratic/song/12039 would remove your vote for the specified song.