API 5 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)

Rules regarding dates

There are 2 date formats used in the API:

The Ampache handshake method returns dates in ISO 8601

{
"session_expire": "2021-08-20T12:20:26+10:00",
"update": "2021-07-21T12:51:36+10:00",
"add": "2021-08-03T10:04:14+10:00",
"clean": "2021-08-03T10: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-01T10:00:00+10:00",
"sync_date": "2021-08-20T11:08:30+10:00",
"podcast_episode": [
{
"pubdate": "2021-08-17T23: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

Debate resolved. Ampache 5.0.0 will rename Tag and remove the old genre variable.

Genre will provide a genre ID as well as the name

<genre id="20" count="1" ><![CDATA[Metal]]></tag>
<genre id="37" count="1" ><![CDATA[Hard Rock]]></tag>
"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 will be removed in Ampache 5.0.0

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