[API Request] Support JSON post for new endpoints ?

[Tolriq]

Type of change

API tweak

Proposal description

This is just as starting discussion to evaluate if servers / clients would embrace supporting posting JSON for some new endpoints.

This would simplify the definition of complex new APIs like transcoding profiles and filtering, multi sorting and everything we could do with the getAllXXX endpoints for example.

Backward compatibility impact

No response

Backward compatibility

• No backward compatibility impact.

API details

Allowing some endpoints to support posting a JSON instead of a very long and complex parameter list that would require specific encoding if we need to pass complex objects in them.

Security impacts

No response

Potential issues

No response

Alternative solutions

No response

[epoupon]

Yes
(Why not?)

[Tolriq]

I don't know why not, but better to ask than build proposals rejected because some object.

[paulijar]

I have no objections. One pain point in the original Subsonic API is how the list type parameters are handled, e.g. songId on the API method createPlaylist. The repeated URL argument with the same name is really awkward to handle at least in PHP. Using JSON type arguments in the new API methods would certainly be one way to avoid having this problem in the future.

Stating the obvious, we then need to make sure that the supported JSON contents are very clearly documented, e.g. which properties as mandatory and which are optional and what are the data types of each property.

[Tolriq]

We should use JSON Schema for that, it should cover a large part of the definition and would help clients.

[Tolriq]

@opensubsonic/servers @opensubsonic/clients This is the first step to move on new endpoints please take time to write a simple yes or no with some details.

[jeffvli]

Yes.

As a consumer of the API I welcome any change that makes it simpler to use.

[deluan]

Yes, for new endpoints. But IMO we should require a proper JSONSchema or OpenAPI definition doc when introducing the new endpoints, to avoid us getting to the same state we are with the old ones.

[Tolriq]

Some endpoints can return different things depending on the id being album or artists or podcast or track and it's then not possible to properly describe what are the mandatory field and default values for the different cases leading to wrong definition. Same for the auth, there's 3 different auth that each requires different kind of parameters.

The main selling point of having a full openAPI definition was to be able to clients to autogenerate the API wrappers for their language.

If there's still a way to properly document things and generate a swagger wrapper for example, then it's probably good enough to not enforce the mandatory fields for now and have most optional.

[Gr3q]

If there's still a way to properly document things and generate a swagger wrapper for example, then it's probably good enough to not enforce the mandatory fields for now and have most optional.

That is the only way to go, see below (and recommended by OpenAPI itself).

Some endpoints can return different things depending on the id being album or artists or podcast or track and it's then not possible to properly describe what are the mandatory field and default values for the different cases leading to wrong definition.

The response depending on a query parameter cannot be described in OpenAPI (I know ID in the docs is already ambiguous) so the schema can just describe the union of all possible return values if necessary.

I haven't found the proper distinction for a response in the docs that you are talking about yet but I'm only at endpoints starting with d. What I found is that Child is definitely very permissive but I can't add more restrictions to the openapi.json than what is in the current docs.

Same for the auth, there's 3 different auth that each requires different kind of parameters.

Not possible to describe in OpenAPI 3, will be possible in OpenAPI 4 though. I don't see this a problem with opensubsonic.

Edit: I'm most likely going to open a PR with the OpenAPI spec in this repo when I'm done (hopefully it can be accepted without xml - although adding the xml responses should not be that big of a job as long as it's documented)

[Tolriq]

The auth param groups would help as you can't mix them and many servers will errors. But again this is mostly an issue for autogenerating the clients code.
I suppose we can warn that it won't work and it should be used as documentation only.

Edit: For the PR I think it's best if the API is build with different files and not one single massive 10k lines when finished with everything and the examples, ....

[Gr3q]

In this repo it can live in different files and the root file almost exclusively contains refs which can be resolved when the full specs need to be built (it can has some caveats with resolving, depending on the library used but that's just implementation)

I'm building it in one file because as I go:

• I'm testing doc generation
• I'm testing client generation
• Almost everything expects it to be a single file

I can break it up afterwards, but in the end something need to be server that can generate docs/clients conveniently by just pointing to it.

[Tolriq]

Yeah, the problem is that I don't see how we can auto generate the large json from the current specs, this means that rebase, merge when multiple things changes in multiple PR are quickly a pain :(

IMO if it's possible having it split in json or yaml and have a task in the build system that generate the global json to serve with swagger would be best.