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:
- Unix epoch time (e.g. 1629345129)
- ISO 8601 date (e.g. 2004-02-12T15:19:21+00:00)
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)