Standards

API Standards​

Here are some basic standards that all Ampache API's should follow.

There will be inconsistencies between the current API's and we will be working on merging to a clear set of standards.

Rules regarding objects and data​

For now, here are a few basic rules that the API should follow:

• ID is a string for all objects.
• Everything that has an ID should include this in the response.
• All other integers are cast to int
• Same thing for doubles
• null and empty values may be returned. (for example XML will always return an object but it may not have any value)

XML attributes and elements​

• Any object that has an ID will add that as an attribute to the repsonse
• All other information is to be returned as an element

<albumid="2">
<name><![CDATA[Colorsmoke EP]]></name>
</album>

The exception to this is for success & error messages which return a code attribute.

<successcode="1"><![CDATA[successfully updated: temp_user]]></success>

The message is also not an element.

<errorcode="400"><![CDATA[User does not have access to this function]]></error>

Rules regarding dates​

There are 2 date formats used in the API:

• Unix epoch time (e.g. 1629345129)
• ISO 8601 date (e.g. 2004年02月12日T15:19:21+00:00)

The Ampache handshake method returns dates in ISO 8601

{
"session_expire":"2021年08月20日T12:20:26+10:00",
"update":"2021年07月21日T12:51:36+10:00",
"add":"2021年08月03日T10:04:14+10:00",
"clean":"2021年08月03日T10:05:54+10:00",
}

Podcasts and Podcast Episodes objects also return ISO dates for the following fields

• podcast object "build_date" and "sync_date"
• podcast_episode object "pubdate"

{
"build_date":"1970年01月01日T10:00:00+10:00",
"sync_date":"2021年08月20日T11:08:30+10:00",
"podcast_episode":[
{
"pubdate":"2021年08月17日T23:00:00+10:00",
}
]
}

All remaining Ampache dates should be returned as an integer using Unix epoch time

{
"last_add":1627949046,
"last_clean":1627949154,
"last_update":1626835896
}

Tag is being renamed into Genre​

Ampache 5.0.0 renamed all tag objects into genre and removed the old genre element from the object.

Genre will provide a genre ID as well as the name​

<genreid="20">
<name><![CDATA[Metal]]><name>
</genre>
<genreid="37">
<name><![CDATA[Hard Rock]]><name>
</genre>

"genre":[
{
"id":"4",
"name":"Electronic"
},
{
"id":"77",
"name":"Experimental"
}
],

Remove spaces from advanced_search rule names. (Backwards compatible with old names)​

These rules have been changed to make sure everything has no spaces. The backward compatible names were removed in Ampache 5.0.0

• 'has image' => 'has_image'
• 'image height' => 'image_height'
• 'image width' => 'image_width'
• 'filename' => 'file' (Video search)