query: switch Accept-Query to SF (closes #2934) #2935
Conversation
| 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"/>), |
There was a problem hiding this comment.
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".
There was a problem hiding this comment.
That's intentionally.
There was a problem hiding this comment.
a justification for the intentional "explicit media types, no wildcards" (either in the Issue or here) would be appreciated.
There was a problem hiding this comment.
We discussed this in the other ticket: what's the use case? Can you give an example?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
| <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"/>), | ||
| represented by a List Structured Header Field, containing | ||
| Token Items, optionally parameterized (<xref target="STRUCTURED-FIELDS" section="3"/>). |
There was a problem hiding this comment.
What is/are the type(s) of the parameters?
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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).
There was a problem hiding this comment.
Though not likely useful, q=0.9 would be sf-decimal .
| </t> | ||
| <ul> | ||
| <li>The choice of Token vs. String is semantically insignificant.</li> |
There was a problem hiding this comment.
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."
There was a problem hiding this comment.
Ok. Not sure about MAY/SHOULD/MUST though.
| </t> | ||
| <t> | ||
| The order of types listed by the Accept-Query header field is not significant. | ||
| Note: |
There was a problem hiding this comment.
Is this really a note, or just a list of important considerations. Does it need to be a list?
There was a problem hiding this comment.
I thought a list would be more readable. Do you suggest to make it a plain paragraph?
Co-authored-by: Martin Thomson <mt@lowentropy.net>
Co-authored-by: Martin Thomson <mt@lowentropy.net>
Co-authored-by: Martin Thomson <mt@lowentropy.net>
|
@mnot , @martinthomson , @MikeBishop : "This branch cannot be rebased due to conflicts" - what's going on here? |
| "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, |
There was a problem hiding this comment.
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.
Summary:
TODO: