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
The exception to this is for success & error messages which return a code attribute.
<success code="1"><![CDATA[successfully updated: temp_user]]></success>
The message is also not an element.
<error code="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-12T15:19:21+00:00)
The Ampache handshake method returns dates in ISO 8601
Podcasts and Podcast Episodes objects also return ISO dates for the following fields
- podcast object "build_date" and "sync_date"
- podcast_episode object "pubdate"
All remaining Ampache dates should be returned as an integer using Unix epoch time
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
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)