Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

query: switch Accept-Query to SF (closes #2934) #2935

Open
wants to merge 12 commits into
base: main
Choose a base branch
from
Open

query: switch Accept-Query to SF (closes #2934) #2935

Changes from 2 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
8cf8919
query: switch Accept-Query to SF (closes #2934)
reschke Nov 5, 2024
35d91d4
query: switch Accept-Query to SF - fix typo
reschke Nov 5, 2024
d1fac65
Merge branch 'main' into reschke/2934
reschke Nov 16, 2024
b74eafa
Merge branch 'main' into reschke/2934
reschke Nov 19, 2024
ae9c91a
Merge branch 'main' into reschke/2934
reschke Nov 19, 2024
6beb12f
query: media type for SQL is application/sql (RFC6922)
reschke Nov 13, 2024
9758157
query: SF syntax for Accept-Query (closes #2934)
reschke Nov 19, 2024
55e4508
Merge branch 'main' into reschke/2934
reschke Nov 20, 2024
21771a5
query: SF- fix typo
reschke Nov 20, 2024
41336d5
query: SF - adjust language about media range wildcards
reschke Nov 20, 2024
7bc7757
query: SF - rephrase note
reschke Nov 20, 2024
ee815a3
query: sf - whitespace
reschke Nov 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 32 additions & 10 deletions draft-ietf-httpbis-safe-method-w-body.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -285,27 +285,35 @@ q=foo&limit=10&sort=-published

<section title="The &quot;Accept-Query&quot; Header Field" anchor="field.accept-query">
<t>
The "Accept-Query" response header field &MAY; be used by a resource to
The "Accept-Query" response header field can be used by a resource to
directly signal support for the QUERY method while identifying
the specific query format media type(s) that may be used.
</t>
<sourcecode type="abnf">
Accept-Query = 1#media-type
</sourcecode>
<t>
The Accept-Query header field specifies a comma-separated listing of media
types (with optional parameters) as defined by
<xref target="HTTP" section="8.3.1"/>. <cref>field syntax currently discussed in <eref target="https://github.com/httpwg/http-extensions/issues/2860"/></cref>
"Accept-Query" contains a list of media types (<xref target="HTTP" section="8.3.1"/>),
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sorry, i missed this on first review. here you're saying "a list of media types" with reference to the "Media Types" section of RFC 9110. however, "Media Types" doesn't allow wildcards like image/*. for that you need "Media Ranges".

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's intentionally.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

a justification for the intentional "explicit media types, no wildcards" (either in the Issue or here) would be appreciated.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We discussed this in the other ticket: what's the use case? Can you give an example?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sorry, i'm not finding where a decision to not allow wildcards was made. i saw you mention */* in #2860 (comment) , and in #2860 (comment) you list as an open question

how does a server say that it supports any format? Does this make any sense at all? We currently require one value, and IMHO we can stick with that

which i took to mean "at least one value".

a use case that comes immediately to mind is a fancy AI™-powered image search that can accept any image type (at least as "any" as a web browser that tells a server it accepts any image type):

Accept-Query: image/*

a possible use case for */* could be a query-by-value of a collection/container resource: given any kind of serialization of any kind of object, answer my contained URI of a resource (and maybe metadata about it) if i happen to contain a resource matching that serialization and media type, or 204 if i don't.

Copy link
Contributor Author

@reschke reschke Nov 15, 2024 •
edited by martinthomson
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not convinced by these use cases, for "image/*" I would expect that more than the image would be needed, thus some kind of multipart would be used. For "*/*", the situation seems similar.

With that said, I'd propose the simplest possible way to get this resolved would be to indeed allow these values.

represented by a List Structured Header Field, containing
Token Items, optionally parameterized (<xref target="STRUCTURED-FIELDS" section="3"/>).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is/are the type(s) of the parameters?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

that's a good question - I guess "token or string" - or we can restrict them to strings

re: token vs string - it just occured to me that if we use strings instead of tokens (in general), we lose nice properties wrt leading/trailing whitespace.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the parameter-value of a media-type or media-range can be a token or a quoted-string. in order to express media types and their parameters in a SF as commonly given, both token and quoted string need to be supported. quoted string is definitely needed because some media types' parameters (can) have spaces in them that mean something (for example, the profile parameter of application/ld+json).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Though not likely useful, q=0.9 would be sf-decimal .

</t>
<t>
The order of types listed by the Accept-Query header field is not significant.
The order of types listed in the field value is not significant.
</t>
<t>
Accept-Query's value applies to every URI on the server that shares the same path; in
other words, the query component is ignored. If requests to the same resource return
different Accept-Query values, the most recently received fresh (per
<xref target="HTTP-CACHING" section="4.2"/>) value is used.
</t>
<t>
Example:
</t>
<artwork type="example">
Accept-Query: application/jsonpath, application/sql;charset="UTF-8"</artwork>
<t>
Note that although the syntax appears to be similar to other
reschke marked this conversation as resolved.
Show resolved Hide resolved
fields, such as "Accept" (<xref target="HTTP" section="12.5.1"/>),
it is a Structured Field and thus &MUST; be processed as specified in
<xref target="STRUCTURED-FIELDS" section="4"/>.
</t>
</section>

<section title="Examples" anchor="examples">
Expand Down Expand Up @@ -543,9 +551,9 @@ Dubois, Camille, camille.dubois@example.net
<tr>
<td>Accept-Query</td>
<td>permanent</td>
<td></td>
<td>List</td>
<td><xref target="field.accept-query"/> of this document.</td>
<td><cref>field syntax currently discussed in <eref target="https://github.com/httpwg/http-extensions/issues/2860"/></cref></td>
<td/>
</tr>
</tbody>
</table>
Expand Down Expand Up @@ -578,6 +586,19 @@ Dubois, Camille, camille.dubois@example.net
<seriesInfo name="STD" value="98"/>
<seriesInfo name="RFC" value="9111"/>
</reference>
<reference anchor="STRUCTURED-FIELDS">
<front>
<title>Structured Field Values for HTTP</title>
<author initials="M." surname="Nottingham" fullname="Mark Nottingham">
<organization>Cloudflare</organization>
</author>
<author initials="P-H." surname="Kamp" fullname="Poul-Henning Kamp">
<organization>The Varnish Cache Project</organization>
</author>
<date year="2024" month="September"/>
</front>
<seriesInfo name="RFC" value="9651"/>
</reference>
</references>

<section title="Change Log" anchor="change.log" removeInRFC="true">
Expand Down Expand Up @@ -628,6 +649,7 @@ Dubois, Camille, camille.dubois@example.net
<section title="Since draft-ietf-httpbis-safe-method-w-body-06" anchor="changes.since.06">
<ul>
<li>Editorial changes to Introduction (ack Will Hawkins, <eref target="https://github.com/httpwg/http-extensions/pull/2859"/>)</li>
<li>Make Accept-Query a Structured Field (<eref target="https://github.com/httpwg/http-extensions/issues/2934"/>)</li>
</ul>
</section>
</section>
Expand Down