To be able to move forward and start to take decision and formalize more things it’s important to get some more validation from the server side on their wishes.
It would be nice if all server authors could add a post on this thread to confirm if they are still interested in this project, and add some comments about what they want as formalism or if current one is OK and how they want to move forward.
I’m adding also a small pool about the main choices that where exposed too.
Optional extensions (Allows non breaking change to current API)
Rigid API versioning (Version 1.17.x, no changes to current API)
Still interested
About API versioning, even if we add some backward compatible changes (like adding new optional fields in response), we will end up adding new endpoints, and thus need to increase the supported version number.
I have the feeling we would need either to increase the version number at each change or switch to a more flexible v2 API with “dynamic” capabilities
I’ve detailed the proposal for dynamic optional capabilities in the sub forum.
API version number are generic, and if endpoint are optional they do not bring anything useful for all the current uses cases.
field in response saying that you support extensions.
One api endpoint to list the extensions you support and the versions of each extensions to allow iteration on extensions.
Current API 1.16.1 define a large number of endpoinds and many servers does not implement all of them and return each different undocumented “not implemented” errors. So the API version already means nothing in production.
Building a version 1.17 would not bring any benefit for the clients as we would still have to behave differently based on what the server name and version are and not what an official new endpoint says you support.
I mean just take LMS example you say 1.16 but do not support the new auth system that you are supposed to support since 1.14. There’s no proper way to tell that to consumers so you returned an error p param missing that makes no sense in the context of the API definition.
For this specific case, majority of servers have decided to cheat and use the error 41 that you now use too. But this is still cheating and not respecting the API definition.
And for the auth case since it’s bad solution I understand why, but still, there’s an API version that is meaningless.
Hence the proposal about extensions. Or building a new API. But I really, really do not think that building an API 1.17 is a good idea as it will just make the client life harder for 0 benefits. And the goal of this is to simplify the life of servers and clients not makes things worse.
I’ve been running a commercial API for over a decade now, and one of the best decisions I made was to version stamp the endpoints.
However…
That’s a completely different use case where there is one server and multiple clients. In this case we are also dealing with multiple server implementations.
I would back an approach which does version stamp the API going forward (this gives us the flexibility in the future), but also includes the extensions approach. While we just add extensions there’s no need to update the version stamp. If we decide (say) the extension model itself needs refinement and a change in schema then we can update the version stamp.
What we ended up with in the case of search, search2 and search3 was pretty nasty…
So I didn’t know what to vote for
But yes, I am interested. I also mentioned this project to someone on Reddit the other day who also seemed like they wanted to re-invent this particular wheel.
The main pain point is that current API is 1) a mess 2) already not properly implemented by most.
The main argument I try to convey is that building something rigid on an already broken basis can’t work long term.
I’m all OK to build an new API or a v2 API and build upon that but it’s a lot more work for all the servers and potentially the clients at unmaintained client would no longer work.
That’s why I also advocate for the pure optional extension way. No rigidity and tons of flexibility for both parties, yet without adding API mess by having a simple but effective way to document the extensions.
That’s why the decision is on the server end today.
But really IMO from 10 years of dealing with tons of media related API and all their evolution. Building something rigid mostly called 1.17 is a bad idea as does not solve anything about the current mess and won’t help building a better future for either the clients or the servers.
Naive question: what is the point of a brand new V2 API then? Isn’t there already some existing “audio” API that already fit all our needs? (Kodi? I guess @Tolriq can answer this?)
Kodi does not handle audiobooks/podcast at all, lacks playlist edit API and lack transcoding.
Currently there’s no perfect API for Audio that covers everything Not talking about some features some servers currently have and may want to expose via this API too.
A new open standard could improve the whole ecosystem but I doubt that this will happen. Plex will keep it’s private same for Kodi Emby or Jellyfin.
Subsonic API is the standard that is currently used by more servers than just it’s originator.
The thing with this is that it’s almost always the de facto emergent “winners” in the category whose API will be adopted. We can strive for perfection but still be beaten (TCP/IP vs OSI anyone?)
The thing is that the protocol already exist and is already not respected and we are trying to see if it’s fixable or not.
Adding rigid blocks over an unstable base can’t work long term. It will just add more differences between the servers leading to less client adopting leading to the need for something new with 5 of 6 different servers trying to build, leading to not much.
So we can either directly try to build something new and stable to gain a lot of years. Or we can try to be pragmatic and offer a way to add some stability and solidity to the current base via subtle extensions that can bring a new proper base to keep iterating on. Both options are very very different in time investments from all the parties and one is a lot riskier than the other.
Or we can also do nothing, but I doubt this would be beneficial to any one. The goal here is really to expand the Subsonic current ecosystem to offer improved user and server experience. The more healthy this is, the best for all parts.
And just to be clear one more time, Symfonium is built to be agnostic of the media provider and their API. Adding support for a new API is really really easy for me. But while it’s good for that server to have one more client and for me to be one of the few client, this is not good for the users and the rest of the community.
I’m really just here as a mediator, with experience in dealing with Media Providers API since a very very long time in Yatse.
As it has already been said, the current API is a mess. It’s vaguely defined and different implementers (both producers or consumers) can give different interpretations to a same concept. Plus the fact that a single object type can represent different concepts (i.e. the folders that can be considered as artists or albums under some unknown conditions).
Several times I wanted to say “f*** it” and just define my own API to clean up all this but didn’t go that route as it would mean also developing my own client, something I’m not willing to do.
I don’t think building on the current API is a good idea. Adding bricks to an already unstable foundation will only lead to an even more wobbly building. Even if we properly redefine the already existing concepts through an extension API, we’d still have to keep the old implementation in order to maintain compatibility, requiring more work (at least server-side) to maintain multiple implementations and bringing even more confusion on both clients and servers as you’d now have several ways to do more or less the same thing.
I feel like keeping the the V1 API will prevent the ecosystem from properly moving forward in the long run. Sure a V2 will require work on both clients and servers but you can’t strive to keep compatibility forever, at some point it will become a hindrance. Unmaintained clients won’t be supported anymore but since they’re already dying they’ll progressively be replaced by new shiny ones, I don’t see the point in keeping them on life support.
Adding or improving features through new endpoints on the existing API will somehow be the same as creating a new API anyway, both clients and servers will have to work to support them, with the additional constraint of keeping a compatibility layer in the case of the V1+extensions API. Why not just drop the old one then?
If we go for a new API, there’s nothing preventing servers from exposing it from another path the old one did, say /rest (sic) for the V1 and /2 for a V2, thus allowing to run both in parallel and so keeping compatibility if we ever want to. How clients handle this will be up to them; either they drop the V1 and only support V2 or try to request V2 and fallback to V1 if it isn’t available, some already do something similar when they handle errors on some endpoints to see if the feature is available.
As a final note, client developers are currently left out but I think they should be an integral part of these discussions. By excluding them, even if it’s only for an initial phase, we’re basically deciding what’s good for them and imposing our vision on them without their say on the matter.
Just a quick note there’s already at least 3 clients here.
But current first target is to see if servers have a willing to move to somewhere or not and what investment they want / can commit.
Adding tons of clients will only makes this more difficult. If servers can’t agree on the start, there’s no point in adding more targets as nothing will move.
I agree with @spl0k points but I’m willing to do whatever the group decides. What I really want to see is feedback/participation from other major maintained clients (Sonixd, Substreamer, play:Sub, Subfire…)
As soon as we know the server direction we can start the GitHub org and move with more clients. But I do not think clients putting pressure on the servers to go somewhere would be beneficial and may just make them fly away.
We already lost Ampache on the road.
If everyone agrees for both options without a clear winner, next step would then be to ask other clients.
But to first create the Github org to reduce friction of discussing all this on a client forum.
To gain time if you agree, you can directly propose a name for the public organisation that would lead the project. (I’m bad at naming, but it would probably require a different name than Subsonic to avoid issues?)
Not talking about some features some servers currently have and may want to expose via this API too.