[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]

I think you said it was not possible to cover current API with a full OpenAPI ?

I'm only familiar with JSONschema hence why I proposed it above but anything simple to either generate from something or already be easily "diffable" to review PR works.

And it must be something that does not prevent or interfere with the previous endpoints if a client decide to use those definitions to generate client code automatically.

[deluan]

Yeah, I though about using OpenAPI only for new endpoints, to describe the payload, it would also allow code generation for the models and validation, but it could be confusing to have only new endpoints in OpenAPI.

On the flip-side, AFAIK JSONSchema only allows one object definition per file. Anyway, I agree, JSONSchema seems to be a better approach here.

What is important is, IMO: We should not add new endpoints without a schema.

[Tolriq]

What is important is, IMO: We should not add new endpoints without a schema.

Yes that's a given.

If you can think about a way to make OpenAPI as a global solution without being weird for the previous endpoints then it's better to have one file to ease code generation.

Else with JSONSchema I would have made 1 schema per endpoint and a global schema with $ref to the rest (but that would more be a directory of schema than something really documenting the API)