====== Ampache's XML API DEVELOPMENT VERSION ======

**API Versions:** {[[dev:XmlApi|Current Stable (3.5.x)]]} {[[dev:xmlapi:development|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 [[http://amarok.kde.org/|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 [[Config:Acl|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 [[http://ampache.org/bugs|Feature Request]]. All dates in the API calls should be passed as [[http://en.wikipedia.org/wiki/ISO_8601|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 [[dev:XmlApi:Error|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. 

==== Read Methods ====