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 all 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
54 changes: 44 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 @@ -321,26 +321,46 @@ 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 ranges (<xref target="HTTP" section="12.5.1"/>)
using "Structured Fields" syntax (<xref target="STRUCTURED-FIELDS"/>).
Media ranges are represented by a List Structured Header Field of either Tokens or
Strings, containing the media range value without parameters. Parameters,
Copy link

@zenomt zenomt Nov 23, 2024 •
edited
Loading

Choose a reason for hiding this comment

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

saying "Parameters, if any, are mapped to Parameters of type String" is both unnecessarily prescriptive and confusing. if i say application/foo+json; x=3.1, where parameter x is (or could be interpreted as) a SF decimal, i should (1) be allowed to say it that way (that is, i shouldn't be forced to say application/foo+json; x="3.1"), and (2) it's nobody else's business whether i, when receiving this field, treat the 3.1 as a string or a number. that should be between the definition & semantics of the media-type/range and my implementation.

how about words like

"Parameters of the media-range, if any, are mapped to Structured Field Parameters. The media-range with its parameters <bcp14>MUST</bcp14> be parsable as a valid Structured Field."

perhaps using "expressed" or "serialized" in place of "mapped" in the first sentence.

if any, are mapped to Parameters of type String.
</t>
<t>
The order of types listed by the Accept-Query header field is not significant.
Note:
Copy link
Contributor

Choose a reason for hiding this comment

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

Is this really a note, or just a list of important considerations. Does it need to be a list?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I thought a list would be more readable. Do you suggest to make it a plain paragraph?

</t>
<ul>
<li>The choice of Token vs. String is semantically insignificant.</li>
Copy link
Contributor

Choose a reason for hiding this comment

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

This doesn't obviously map to a normative requirement. I think that you might need to add something like "Implementations MAY convert Token values into Strings when processing."

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Ok. Not sure about MAY/SHOULD/MUST though.

<li>Media types do not exactly map to Tokens, for instance they
allow a leading digit. In cases like these, the String format needs to
be used.</li>
<li>The only supported uses of wildcards are "*/*", which matches any type,
or "xxxx/*", which matches any subtype of the indicated type.</li>
<li>The order of types listed in the field value is not significant.</li>
<li>The only allowed format for parameters is String.</li>
</ul>
<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.
different Accept-Query values, the most recently received fresh value (per
<xref target="HTTP-CACHING" section="4.2"/>) is used.
</t>
<t>
Example:
</t>
<artwork type="example">
Accept-Query: "application/jsonpath", application/sql;charset="UTF-8"</artwork>
<t>
Although the syntax for this field appears to be similar to other
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>

Expand Down Expand Up @@ -458,6 +478,19 @@ Accept-Query = 1#media-type
<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>
<references title="Informative References">
<reference anchor="FETCH" target="https://fetch.spec.whatwg.org">
Expand Down Expand Up @@ -688,6 +721,7 @@ Dubois, Camille, camille.dubois@example.net
<li>Editorial changes to Introduction (ack Will Hawkins, <eref target="https://github.com/httpwg/http-extensions/pull/2859"/>)</li>
<li>Added Security Consideration with respect to Normalization (<eref target="https://github.com/httpwg/http-extensions/issues/2896"/>)</li>
<li>Added CORS considerations (<eref target="https://github.com/httpwg/http-extensions/issues/2898"/>)</li>
<li>Make Accept-Query a Structured Field (<eref target="https://github.com/httpwg/http-extensions/issues/2934"/>)</li>
<li>SQL media type is application/sql (RFC6922) (<eref target="https://github.com/httpwg/http-extensions/issues/2936"/>)</li>
<li>Added overview table to introduction (<eref target="https://github.com/httpwg/http-extensions/issues/2951"/>)</li>
<li>Moved BCP14 related text into subsection (<eref target="https://github.com/httpwg/http-extensions/issues/2954"/>)</li>
Expand Down