Clarify what query parameters mean in thirdparty endpoints

[wfdewith]

The /_matrix/client/r0/thirdparty/location/{protocol} endpoint specifies a searchFields query parameter with type string, but the description mentions it's: "one or more". What is the actual format for this query parameter?

The same is also true for /_matrix/client/r0/thirdparty/user/{protocol}, the only difference being that the query parameter is called fields.... I found in api/openapi_extensions.md that it is supposed to mean "one or more", but no specification on the actual format.

[wfdewith]

Also note that Synapse seems to not even use those query parameters at all:
https://github.com/matrix-org/synapse/blob/08b2868ffe5e103beefbcf4c4764224c610c5ce4/synapse/rest/client/v2_alpha/thirdparty.py#L68
https://github.com/matrix-org/synapse/blob/08b2868ffe5e103beefbcf4c4764224c610c5ce4/synapse/appservice/api.py#L134

[Half-Shot]

Also note that Synapse seems to not even use those query parameters at all:
https://github.com/matrix-org/synapse/blob/08b2868ffe5e103beefbcf4c4764224c610c5ce4/synapse/rest/client/v2_alpha/thirdparty.py#L68
https://github.com/matrix-org/synapse/blob/08b2868ffe5e103beefbcf4c4764224c610c5ce4/synapse/appservice/api.py#L134

I think you might be confused. The query parameters are called fields in those examples, and they are basically forwarded onto the appservice.

The /_matrix/client/r0/thirdparty/location/{protocol} endpoint specifies a searchFields query parameter with type string, but the description mentions it's: "one or more". What is the actual format for this query parameter?

The same is also true for /_matrix/client/r0/thirdparty/user/{protocol}, the only difference being that the query parameter is called fields.... I found in api/openapi_extensions.md that it is supposed to mean "one or more", but no specification on the actual format.

It's not terribly clear, but the search fields are defined in https://matrix.org/docs/spec/client_server/r0.6.0#get-matrix-client-r0-thirdparty-protocol-protocol (user|location)_fields. The names of those fields are defined in there, and the format of the value of those fields are defined in field_types. The example response should clear things up.

[wfdewith]

I think you might be confused. The query parameters are called fields in those examples, and they are basically forwarded onto the appservice.

Yeah, you're right, I skimmed that code too fast. However, if those parameters are just forwarded onto the appservice, then there is still a bug in either the client-server API spec or the application service API spec for the GET /_matrix/client/r0/thirdparty/location/{protocol} endpoint, since the query parameter is searchFields in the client-server spec, and fields... in the application service spec

It's not terribly clear, but the search fields are defined in https://matrix.org/docs/spec/client_server/r0.6.0#get-matrix-client-r0-thirdparty-protocol-protocol (user|location)_fields. The names of those fields are defined in there, and the format of the value of those fields are defined in field_types. The example response should clear things up.

I know that they're effectively strings with a regex constraint, but what I don't know is how to represent one or more strings in a query parameter. For example, is it: ?fields=foo,bar, ?fields=foo&fields=bar, ?fields[]=foo&fields[]=bar or something else? And shouldn't the type of the query parameter in any case be clearer than just string?

[Half-Shot]

It's not fields in the query parameter, it's foo=value1&bar=value2. The field names are query parameters. The parameters themselves can only have 1 string value per search, which is a limitation of the API.

The fields... in the AS API is implying this, the ... means do not use the fields name literally but replace with your search fields.

[wfdewith]

Oh wow, now I can't believe I misinterpreted that. Thanks for the clarification!

Would it be useful to add an example of this to the specification?

[Half-Shot]

Yes, given it seems to be confusing people it's crying out for a good example :)

[wfdewith]

Creating an example will be way easier once the specification uses OpenAPI 3.0, as dynamic query parameters aren't natively supported in OpenAPI 2.0. For now it's probably easier to just make the description for those fields... parameters a little more explicit.

[turt2live]

According to our own extensions, fields... is wrong for this because it would literally translate to ?field=alice&field=bob. Fixing this involves also fixing how we define it.

[wfdewith]

Should I open a new issue, because that seems a bug in the spec itself.

[turt2live]

This bug is fine, it's the same issue. The spec could do with clarification, and that clarification work will also handle fixing the extensions.

[deepbluev7]

The openapi spec should now be correct with 1405184 and #1947. The text/rendering of the spec might still be unclear though.

For me it wasn't immediately obvious why that is the case though, so let me explain (for future me for example):

• The query parameters are now objects (of string: string)
• The query parameters use the default style: form
• In that case the explode option defaults to true, which expands the object into separate query parameters

References:

• https://swagger.io/docs/specification/describing-parameters/#query-parameters
• https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#fixed-fields-10

[richvdh]

Since things have changed a bit since this issue was opened, I've opened a new one to summarise the situation: #1993.