Ampache5 API

[memen45]

Just wanted to notify that Ampache has released a new API version, Ampache5. I was wondering if you were planning to implement the changes in the near future as well!

[paulijar]

I'm probably not going to dive all the way in to the API v5 any time soon. As most Ampache clients are not actively maintained, I don't want to break the compatibility with the API versions 3 and 4. I could still incorporate some of the additions of the APIv5; at least the bookmark support might make sense, provided that it is compatible with the bookmark system of the Subsonic API (the examples are currently missing from the API spec).

[memen45]

Yes, I am having the same doubts with regards to implementation on client side. The array responses have been updated from

[ {}, {}, {}, ... ]

to e.g.

{ "playlists": [ {}, {}, {}, ... ] }

So, as a client, it is quite messy to implement both at the same time. However, only implementing one excludes either the legacy users or the updated ones.

[paulijar]

I guess it would be within the realm of possibilities for the Music app to provide support for both API versions 4 and 5, depending on the version argument received on handshake. We should then just store it per session, which API is requested, and make some transformations on the responses. This shouldn't be all that different to how we currently transform the results to either JSON or XML format.

On the other hand, I don't know your client's architecture but ideally, you should be able to preprocess those V5 responses to look like the V4 responses on some common function. After the preprocessing, the result could be dispatched to the same handlers as with V4 API. Of course there probably are some finer details which will make it somewhat more complicated than this, but the overall idea could still work.

[lachlan-00]

in ampache/ampache#3062 (comment) i've laid out the path to supporting multiple versions.

it's something that's been on the wishlist/eventual todo during 5 dev but it's just going to take a while as PHP8 and code quality have taken over API work and I'm pretty much by myself again.

[lachlan-00]

I also wouldn't put the effort into multiple versions as a client, it's not your job.

[lachlan-00]

I'm almost done importing the old API's will update more tommorow.

TLDR is

• send your version number (440000, 5.1.1, 3900001, etc)
• I then record your session data based on major revision (3,4,5)
• return data/perform actions using that version of the api

[lachlan-00]

support added now in ampache/ampache@098518e

https://develop.ampache.dev has been updated so you can try it out there.

[memen45]

@paulijar any update on this? As you mentioned, especially the bookmarks are new in the Ampache5 api, which might make it worth implementing it.

[paulijar]

@memen45 Nope, sorry, not much has happened in this project during this year.

[memen45]

No worries. It's been a while again and got a request regarding this. If I update my app SubMusic to Ampache 5 to support bookmarks, it would break compatibility with all Nextcloud servers. Obviously, I do not want that!

Would it be significantly less work if the implementation of Ampache 5 would be reduced to:

• only support Ampache 5 methods that were already in Ampache 4 (response structure is often the only difference). Skip newly added endpoints (simply return a 4705: Missing or 405 Missing). SubMusic can work around missing bookmark methods.
• allow for versioning in the handshake, but only support the existing Ampache 4 (version=44000) and the new Ampache 5 (version=5.2.0)

Optionally: skip Ampache 5 and go straight to Ampache 6. That one is currently still in development though.

Not sure if it is worth it, though, as I do not know how many users and clients rely on Ampache 5+, let alone Ampache 5+ features. You probably have a better view on this!

[paulijar]

In July, I should again have time to do some development for this project. I'll try to add some level of support for Ampache 5 API during this development sprint.

[lachlan-00]

The change between api 5/6 is minimal. (A fully supported API6 server should be fully compatible with Ampache5) I'm making sure that they're as fully backwards compatible as possible.

Previews are up https://github.com/ampache/ampache/releases/tag/6.0.0-preview1

Added/Changed things in API6 compared to 5.

• JSON responses
  • Cast bool fields to true and false instead of "1" & "0"
  • Add total_count to responses to give clients an idea of the total possible objects
• XML responses
  • Api6 XML success and error response messages are put in a message element (like json)
  • For data responses id is the only attribute and everything else is an element
  • Name was not set as an attribute OR an element so now it's always an element
  • Return original XML output (that may be malformed) when loadxml fails.
• Renamed user_update to user_edit (user_update still works and will be depreciated in API7)
• Albums with no album_artist may now return 0 artist called 'Various'
• Api6::get_indexes: This method is depreciated and will be removed in Ampache 7.0.0 (Use Api6::list instead)

Removed things in API6

• preciserating removed from all objects (use rating)
• Remove non-song MBIDs as not relevant to the object (very unlikely it was used)
• album_songs remove exact as a parameter
• stream remove podcast as a valid type value (it was meant to be podcast_episode)

[lachlan-00]

I forget if i mentioned this before but another option is to make sure you send a api4 version in your strings.

For example sending http://localhost/ampache/server/xml.server.php?action=handshake&auth=PASSPHRASE&timestamp=TIME&version=440001&user=USER

will tell the server that you're using api4 and will send data/responses in the api4 format

After Ampache 5.2 you can send any supported version from api3+ and get the latest supported version of that major release.

[paulijar]

I created a WIP pull request #1078 to follow progress on this topic.

[paulijar]

Music v1.9.1 with support for API versions 3-6 is now finally out. The new version covers quite large portion of the APIv6 specification, including almost all methods which are applicable on this app. Feel free to open a new issue if something important is still missing or something is not working as expected.