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.
The handshake is a combination of the following three things
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×tamp=$time&version=350001&user=vollmerk
If your Password, IP and Username match a row in the Access List the following will be returned.
<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>
All future interactions with the Ampache API must include the TOKEN as a get variable named 'AUTH'.
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.
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.