query method: examples

[reschke]

It would be good to have examples that use a well-defined query language incl media type, and a well-defined response media type.

[reschke]

One obvious use case is to convert use of POST to QUERY. This implies that we should document/use "application/x-www-form-urlencoded", right?

[reschke]

So how do we do it?

Do we just say that the payload format is the same as for POST, and the response format is undefined (but maybe selected by Accept)?

[MikeBishop]

Ultimately, I think these have to be defined by the resource. The client can inform the server what it's sending and express preferences for the response, but there's too much context that the protocol can't specify. So yes, I think it's the same as POST but with safety/idempotency claims around the behavior.

[reschke]

Proposal: use https://www.rfc-editor.org/rfc/rfc9535 for examples (we would just have to figure out the response format)

[reschke]

Proposed structure:

• Simple Query (maybe including a malformed one?)
• Discovery of QUERY support
• Discovery of QUERY formats
• Location and Content-Location
• Redirects: examples for 301/302/307/308 pending until somebody can think of a good example
• Content Negotiation
• Conditional Requests

Potentially combined into fewer examples.

cc: @MikeBishop

[reschke]

...and move them into appendix.

[mnot]

The section should note that these examples are illustrative only; if one needs to send queries that are actually this short, it is probably better to use GET.

[reschke]

Simple Query

QUERY /contacts HTTP/1.1
Host: example.org
Content-Type: application/x-www-form-urlencoded
Accept: application/json

select=surname,givenname,email&limit=10&match=%22email=*@example.*%22

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

[
  { "surname": "Smith", "givenname": "John", "email": "[email protected]" },
  { "surname": "Jones", "givenname": "Sally", "email": "[email protected]" },
  { "surname": "Dubois", "givenname": "Camille", "email": "[email protected]" }
]

[reschke]

Discovery of QUERY support

OPTIONS /contacts HTTP/1.1
Host: example.org

HTTP/1.1 200 OK

Allow: GET, QUERY, OPTIONS, HEAD

[reschke]

Discovery of QUERY formats

HEAD /contacts HTTP/1.1
Host: example.org

HTTP/1.1 200 OK
Content-Type: application/xhtml
Accept-Query: application/x-www-form-urlencoded, application/sql

[reschke]

Content-Location and Location

QUERY /contacts HTTP/1.1
Host: example.org
Content-Type: application/x-www-form-urlencoded
Accept: application/json

select=surname,givenname,email&limit=10&match=%22email=*@example.*%22

HTTP/1.1 200 OK
Content-Type: application/json
Content-Location: /contacts/stored-results/17
Location: /contacts/stored-queries/42
Last-Modifed: Sat, 25 Aug 2012 23:34:45 GMT
Date: Sun, 17 November 2024, 16:10:24 GMT

[
  { "surname": "Smith", "givenname": "John", "email": "[email protected]" },
  { "surname": "Jones", "givenname": "Sally", "email": "[email protected]" },
  { "surname": "Dubois", "givenname": "Camille", "email": "[email protected]" }
]

Content-Location

(Content-Location identifies a resource holding the result for the QUERY response it appeared on)

GET /contacts/stored-results/17
Host: example.org
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json
Last-Modifed: Sat, 25 Aug 2012 23:34:45 GMT
Date: Sun, 17 November 2024, 16:10:25 GMT

[
  { "surname": "Smith", "givenname": "John", "email": "[email protected]" },
  { "surname": "Jones", "givenname": "Sally", "email": "[email protected]" },
  { "surname": "Dubois", "givenname": "Camille", "email": "[email protected]" }
]

Location

(Location identifies a resource that will respond to GET with a fresh result, just like the original QUERY would have)

GET /contacts/stored-queries/42
Host: example.org
Accept: application/json

(one entry removed at 2024-11-17T16:12:01Z)

HTTP/1.1 200 OK
Content-Type: application/json
Last-Modifed: Sun, 17 November 2024, 16:12:01 GMT
Date: Sun, 17 November 2024, 16:13:17 GMT

[
  { "surname": "Smith", "givenname": "John", "email": "[email protected]" },
  { "surname": "Dubois", "givenname": "Camille", "email": "[email protected]" }
]

[reschke]

I'm done with most of these (see branch). The only thing I still want to add is examples that are a bit more interesting.

Anf of course then I'll hear ETOOMANYEXAMPLES. But it's otherwise a short spec, so why not.

Please review: @mnot @martinthomson @MikeBishop (James and Ashok do not seem to be here).

Finish the sectio, declare victory, and get out a new I-D in time before the nextt meeting?

[martinthomson]

I would flip the last two in your content- location/location example. Then you can show that the content-location content is stable. That would require a change to the dates.

Otherwise, this seems like the right amount, not too many.

[reschke]

+1

The one thing I want to add is something with more interestin query formats, combined with the topic of conneg.

[reschke]

@martinthomson - your proposal is to have C-L and 303 in adjacent sections, right?

[desiderantes]

A query format people would be interested in is GraphQL.

[reschke]

@desiderantes - can you provide examples?

[desiderantes]

@reschke

They happen to have a draft for specifying GraphQL over HTTP, but I can cook some examples if needed

[martinthomson]

@martinthomson - your proposal is to have C-L and 303 in adjacent sections, right?

None of your current examples use 303, so I'm not following.

My point was only that you should have QUERY >> GET to Location >> GET to Content-Location, to clearly demonstrate that the last request was unaffected by changes to the underlying resource. I'd show all of those under the same section heading.

[reschke]

Ah. I added 303; there was a race condition with your comment.

FWIW; 303 was added as a sibling section to those. Maybe it makes more sense now?

[martinthomson]

Ah, the 303 example is in the draft, but not this issue. All good.

As far as something like GraphQL goes, I think that what you have is enough. There is no need to show alternatives, unless you want to show content type negotiation for requests as an advanced case.

[reschke]

I'm going to add XSLT/JsonPath as query format examples - I believe we are done then.