query: potential candidate for query format: jsonpath

[reschke]

Spec: https://www.rfc-editor.org/rfc/rfc9535.html

• how to augment the existing media type definition for QUERY (do we need to?
• what response format to use? (application/json)?

[timbray]

If I'm building an API around the new QUERY method, surely I'd have to specify the media types for both query and response, right? So I'm not sure what's special about JSONPath.

[reschke]

The theory is that for a media type to be applicable for QUERY the semantics for QUERY should be specified somewhere. That idea dates back to the time when people just used application/json as payload format for PATCH, with different ideas what that actually means.

But I agree that the semantics for JsonPath with QUERY are pretty clear, maybe except for the question what the JSON document being queried actually is. But that can remain an implementation detail of the server. Any recommendations about what format we should use in the response? Maybe you even could suggest an example?

[timbray]

I disagree at a basic level. A JSONPath selects the parts of some JSON text that it matches. What the JSON text is, and what the effect of selecting parts of it is, seem entirely application-dependent. Maybe it’s applied to the user’s order history and forwards the selected portions to Accounting, and returns status code 200 but no body. Maybe it applies the JSONPath to that same order history, creates an analysis, and returns application/csv. These things are designed to be general-purpose expressions and I really can’t think of anything useful that could be said. -T

…

On Oct 20, 2024 at 9:55:06 AM, Julian Reschke ***@***.***> wrote: The theory is that for a media type to be applicable for QUERY the semantics for QUERY should be specified somewhere. That idea dates back to the time when people just used application/json as payload format for PATCH, with different ideas what that actually means. But I agree that the semantics for JsonPath with QUERY are pretty clear, maybe except for the question what the JSON document being queried actually is. But that can remain an implementation detail of the server. Any recommendations about what format we should use in the response? Maybe you even could suggest an example? — Reply to this email directly, view it on GitHub <#2924 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAEJEZHO73S3LG3L5MQYVLZ4PN6VAVCNFSM6AAAAABQINSZYOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDIMRVGEYTOMJWHE> . You are receiving this because you commented.Message ID: ***@***.***>

[reschke]

Ok, just checking: we don't want to define a standard response format, because we want to leave it specific to the server? I agree with that.

But for an example, would you recommend a specific response format (iff that this is just an example)?

[timbray]

That example of sending a JSONPath which is applied to the user's saved data and returns an analysis in a CSV isn't terrible? Or it might return a nice graph as a JPEG or PDF.

…

On Sun, Oct 20, 2024, 12:34 PM Julian Reschke ***@***.***> wrote: Ok, just checking: we don't want to define a standard response format, because we want to leave it specific to the server? I agree with that. But for an example, would you recommend a specific response format (iff that this is just an example)? — Reply to this email directly, view it on GitHub <#2924 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAEJEZ3XJOF74XEEAEY7ADZ4QAULAVCNFSM6AAAAABQINSZYOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDIMRVGE4DSMZXGU> . You are receiving this because you commented.Message ID: ***@***.***>

[mnot]

I think the difference here is that PATCH has side effects on the resource, whereas QUERY should not (generally). PATCH needed definition to describe those side effects, so it doesn't become another POST escape hatch.

[reschke]

Ok, so we'll just add an example using jsonpath.

[reschke]

Proposal:

QUERY /errata.json HTTP/1.1
Host: example.org
Content-Type: application/jsonpath
Accept: application/json

$..[?@doc-id=="RFC9110" && @errata_status_code!="Rejected"].[errata_id, submit_date]

from a fictious RFC errata database, selects all errata for RFC9110 which have not been rejected, and returns id, submission_date for each

HTTP/1.1 200 OK
Content-Type: application/json

[
  "7105",
  "2022-08-26",
  "7109",
  "2022-08-31",
  "7138",
  "2022-09-23",
  "7306",
  "2023-01-13",
  "7419",
  "2023-04-11"
]

[timbray]

On Nov 1, 2024 at 1:34:45 PM, Julian Reschke ***@***.***> wrote: Content-Type: example/query

Accept: application/jsonpath

That should be Content-Type: application/jsonpath, Accept: application/json, no? Proposal:

…

QUERY /errata.json HTTP/1.1 Host: example.org Content-Type: example/query Accept: application/jsonpath ***@***.***=="RFC9110" && @errata_status_code!="Rejected"].[errata_id, submit_date] from a fictious RFC errata database, selects all errata for RFC9110 which have not been rejected, and returns id, submission_date for each HTTP/1.1 200 OK Content-Type: application/json [ "7105", "2022-08-26", "7109", "2022-08-31", "7138", "2022-09-23", "7306", "2023-01-13", "7419", "2023-04-11" ] — Reply to this email directly, view it on GitHub <#2924 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAAEJE5DR5WYV4B73HCY3PDZ6PQWLAVCNFSM6AAAAABQINSZYOVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDINJSGU2TCMZQGE> . You are receiving this because you commented.Message ID: ***@***.***>

[reschke]

Oh, indeed. Thanks for catching this. Will edit in place.

[reschke]

We could also use this as example of conneg:

HTTP/1.1 200 OK
Content-Type: text/csv

errata_id, submit_date
7105, 2022-08-26
7109, 2022-08-31
7138, 2022-09-23
7306, 2023-01-13
7419, 2023-04-11