query: how to locate description of QUERY-specific semantics of a media type?

[reschke]

How would a reader of the RFCs actually find out what the semantics of a given media type is for QUERY (that is, where it is defined)? Do we need a registry?

[reschke]

We do have the same issue with PATCH:

https://www.rfc-editor.org/rfc/rfc6902
https://www.rfc-editor.org/rfc/rfc7386

Didn't we also define "application/json" as patch format? If so, where?

[martinthomson]

For me, the question is whether we need to say anything. We say nothing much about POST, even for application/x-url-form-encoded and multipart/form-data. Those have a sort-of default semantic, but ultimately the meaning of parameters take on a meaning defined by the resource itself. Same for QUERY, or at least that is what I had always assumed.

[mnot]

That registry is the media type registry - each media type definition needs to define its semantics under applicable methods.

[reschke]

Aha, I read that first as if that was the cause already (which is not the case). Are you suggesting to add that over there? That might be a hard sell...

[reschke]

@mnot - the media type does not have that information.

WRT QUERY: as opposed to PATCH, which has (or is supposed to have) strict semantics based on the format of the target resource and the PATCH body/type, QUERY is much more lenient. So do we actually have to say something? Can't we leave it to servers?

[mnot]

The registry refers to the specification which does have that information.

I don't think it can be left to the servers -- where's the interop?

[reschke]

Only that those specifications have been written prior to the definition of QUERY, so either the specification or the registry would need to be updated.

[MikeBishop]

I feel like these are different ways of saying the same thing, ultimately. The client describes what it's sending with a media type, but needs some a priori knowledge of what the server is likely to accept, both in terms of media type and in terms of semantic content. Ultimately, the answer for this is API documentation, not protocol specification.

I think QUERY's handling of payload should mirror POST as much as possible.

[mnot]

+1 - this is different to PATCH, where we want generic software to process the content; it's more closely coupled because the resource defines the interface. I think this can be closed with no action.

[mnot]

... and to address the specific issue here: I agree the closest analogy is POST. There, it's often resource-specific semantics (i.e., tightly coupled) but the server can choose to use media types (including in Accept-POST) to surface those semantics more generically. Likewise for QUERY.

In both cases, discovering the specific semantics of the format is orthogonal -- while the semantics may be specific to the method, the discovery mechanism isn't baked in, it's through eg OpenAPI, etc.