Repository navigation
Add QUERY method and Accept-Query header references - #45710
Conversation
Adds the HTTP QUERY method defined by RFC 10008 to the HTTP request methods landing page. RFC 10008 defines QUERY as a safe and idempotent HTTP method that carries request content and returns the result of processing that content. The request method table is updated accordingly.
Co-authored-by: Hamish Willee <hamishwillee@gmail.com>
Accept-Query is a List Structured Field of Tokens or Strings, but the Syntax block, Directives and example only showed bare tokens. Add the quoted-string form and mapped media type parameters, and note that the choice between Token and String is semantically insignificant. Add a note contrasting the header with Accept: it is a Structured Field and has no q-values, mirroring the existing note on Accept-Post. Also state explicitly that the header is sent by the server, since the name suggests otherwise, and cross-reference Vary.
The properties table says "Cacheable: Yes" without qualification. Responses are only cacheable if the cache key incorporates the request content and its metadata, which is why caching QUERY is more involved than caching GET. Add prose covering this, along with the Vary header servers send when the response depends on the request content, and the Location fallback that lets clients switch to GET. Also describe the two ways to discover supported query formats: the Accept-Query response header, or issuing the QUERY and reading Accept from a 415 response. The 415 link previously had no explanation.
Review feedback on mdn#44568 noted that the page omitted several parts of RFC 10008 that developers need. Rework the opening, which said QUERY "is useful when the query input is too large or complex for the target URI's query component". That assumed a relationship to GET search queries the page had not established, and framed one use case as the definition. Lead instead with section 2: QUERY initiates a server-side query, and where GET asks for a representation of the target URI, QUERY asks the resource to run an operation within its own scope. The URI length limits then follow as a consequence, with safe and idempotent given as what makes it suitable. Add a Description section, keeping the top short, covering: - Media types and the 400/415/422/406 responses (section 2.1), and the two ways to discover supported query formats. - Equivalent resources (sections 2.2-2.4), distinguishing Content-Location, which holds the result just produced, from Location, which re-runs the query against current data. - Redirection (section 2.5), including that the POST-to-GET exception for 301 and 302 does not apply, and what 303 means here. - Conditional requests (section 2.6). - Caching (section 2.7), moved here from the introduction and extended with cache key normalization and no-transform.
Sections 2.3 and 2.4 of RFC 10008 both defer their examples to the appendices, and the distinction between the two headers is easy to miss in prose alone. Add an example based on Appendix A.4 showing a response that carries both, followed by the two GET requests they enable: one retrieving the stored result unchanged, the other re-running the query so the result reflects current data.
Two normative parts of RFC 10008 were still unrepresented. Appendix A.2 describes how a client discovers that a resource supports QUERY at all, which is distinct from discovering which query formats it accepts. Add a Discovering support section covering OPTIONS with the Allow response header, and the alternative of sending the request and reading Allow from a 405. Format discovery moves here too, so both paths sit together. The Allow link in "See also" previously had no explanation on the page. Section 4 was absent entirely. Add its main point as a Security considerations section: a URI is far more likely to be logged, retained or inspected by intermediaries than request content, so carrying a confidential query in the content is a reason to prefer QUERY over GET. Its two caveats go next to the features they qualify: equivalent resource URIs should not embed sensitive parts of the request content, and a cache whose normalization diverges from the resource can match non-equivalent requests and serve the wrong response.
Section 3 says the field value applies to every URI sharing the same path, and that where requests to the same resource return differing values, the most recently received fresh value is the one that applies. The page covered the first half of that rule but not the tie-break.
Three small corrections after re-reading RFC 10008: - The security wording claimed URIs are "retained in history", which section 4 does not say. Use its own framing instead: a URI is more likely to be logged or otherwise processed by intermediaries than the request content is. - The introduction gave "a JSON filter document" as an example format. Use JSONPath, which is the JSON-based query format the spec actually names alongside application/sql. - Section 3 limits wildcards to "*/*" and "xxxx/*". The Accept-Query page showed both forms but did not say they are the only ones, so a form like "*/json" looked permissible.
github-actions
Bot
added
Content:HTTP
|
@Dijaa I might not get around to reviewing this in a timely manner. Sorry. Adding @chrisdavidmills as well in case I take too long. |
|
Preview URLs (4 pages)
Flaws (3) Note! 3 documents with no flaws that don't need to be listed. 🎉 Found an unexpected or unresolvable flaw? Please report it here. URL:
(comment last updated: 2026-09-23 17:19:59) |
chrisdavidmills
left a comment
chrisdavidmills
left a comment
There was a problem hiding this comment.
Hi there, @Dijaa, and thank you for this work. Overall, I thought it was pretty good — all relevant topics seem to be covered, and I found the writing interesting and informative (I've never read anything about QUERY before, so I guess this makes me a good editorial reviewer candidate)
Most of my comments fall into three categories:
- Grammar/readability suggestions
- Document structure suggestions
- "I'm a beginner, and I don't understand this" type questions.
Have a look through and see what you think. If you don't agree with any comments, I'm happy to hear your responses.
All the best.
| A URI is more likely to be logged, or otherwise processed by intermediaries, than the request content is, so moving a query out of the URI reduces how widely it is exposed. | ||
| Where the query itself is confidential, this is a reason to prefer `QUERY` over `GET`. | ||
|
|
||
| The benefit only holds if the rest of the exchange preserves it, so note the constraints on equivalent resource URIs and on cache normalization described above. |
There was a problem hiding this comment.
Add links to where they are described above?
There was a problem hiding this comment.
Added links to the Equivalent resources and Caching sections
There was a problem hiding this comment.
Great, thanks; I've made a small edit to this section too.
This comment was marked as duplicate.
This comment was marked as duplicate.
Sorry, something went wrong.
|
Thanks for taking this review on @chrisdavidmills ! |
Co-authored-by: Chris Mills <chrisdavidmills@gmail.com>
Co-authored-by: Chris Mills <chrisdavidmills@gmail.com>
Apply suggestions from code review Co-authored-by: Chris Mills <chrisdavidmills@gmail.com>
Updated the documentation for the QUERY method to clarify the handling of request formats, equivalent resources, and caching behavior. Added examples to illustrate the usage of QUERY requests and responses.
Clarified wildcard usage in Accept-Query header documentation.
Dijaa
left a comment
Dijaa
left a comment
There was a problem hiding this comment.
Thanks a lot for the thorough review, @chrisdavidmills, this was really helpful. I've applied most of the suggestions as-is and addressed the open questions inline. In a few places I kept the original meaning where it's tied to the RFC wording (the request-target path, equivalent resources vs. Content-Location), and I explained why in those threads. Let me know if anything still reads unclearly.
| The request content and its {{HTTPHeader("Content-Type")}} define the query; the target resource determines what the query is run against. | ||
|
|
||
| Because the query travels in the request content rather than the URI, it is not constrained by the length and encoding limits that apply to a URI query component. | ||
| This makes `QUERY` a good fit for queries that are too large or too structured to express there, such as a SQL statement or a JSONPath expression. |
There was a problem hiding this comment.
Good question. QUERY isn't meant to replace GET for all queries. When a query is small enough to fit in the URI, GET is still a fine choice, and it has the advantage of producing a URL that can be bookmarked, linked, and cached with no extra work. QUERY is for cases where the URI becomes impractical: large or structured queries, or queries you don't want exposed in the URI. I've reworded this to say that explicitly.
| A URI is more likely to be logged, or otherwise processed by intermediaries, than the request content is, so moving a query out of the URI reduces how widely it is exposed. | ||
| Where the query itself is confidential, this is a reason to prefer `QUERY` over `GET`. | ||
|
|
||
| The benefit only holds if the rest of the exchange preserves it, so note the constraints on equivalent resource URIs and on cache normalization described above. |
There was a problem hiding this comment.
Added links to the Equivalent resources and Caching sections
chrisdavidmills
left a comment
chrisdavidmills
left a comment
There was a problem hiding this comment.
Thanks for the updates, @Dijaa. I made a few direct edits to tweak a few bits. I'm really happy with this now, but I won't merge until you've had a chance to check my edits and make sure you are happy.
Let me know.
|
Thanks for the edits, @chrisdavidmills, they read much better. Two small things, both about staying close to RFC 10008:
Happy for this to be merged once those are in. |
Changes made and merging! Thanks so much for your work on this, @Dijaa, and everyone else who contributed. It's quite exciting to get some |
5 participants
Description
Adds reference pages for the
QUERYHTTP method and theAccept-Queryresponse header, and lists both in the request methods and headers indexes.This continues #44568, which stalled after review. The original commits are preserved here with their authorship, and the review feedback left unaddressed on that PR is resolved in the commits on top.
Motivation
QUERYwas published as RFC 10008 in June 2026 and has no coverage on MDN. It is the first safe, idempotent method that carries request content, so the pages explain what distinguishes it fromGETandPOST, when a query belongs in the request content rather than the URI, and the parts of the specification a developer has to act on: media type errors, equivalent resources, redirection behaviour, conditional requests, and caching.Accept-Queryis documented alongside it because it is the mechanism a resource uses to advertise which query formats it accepts. Its value resemblesAcceptbut is a structured field with no q values, which the page calls out explicitly.Additional details
Everything on both pages is checked against RFC 10008:
Accept-Querysyntax covers the token and quoted string forms and media type parameters mapped to structured field parameters, per section 3.QUERYpage documents the 400, 415, 422 and 406 responses from section 2.1, theContent-LocationandLocationdistinction from sections 2.2 to 2.4, method preservation across all four redirect codes from section 2.5, conditional requests from section 2.6, and the cache key and normalization rules from section 2.7.Two things a reviewer may want to weigh in on:
QUERYhas no browser-specific integration, so both pages usespec-urlsinstead, following the approach suggested on Add HTTP QUERY method and Accept-Query header references #44568. Until RFC 10008 is picked up by browser-specs, the Specifications section renders as "Unknown specification" — flagging that up front so it is not read as a mistake.QUERYis placed directly afterGETin both the list and the properties table on the methods index, since that is the method it is closest to semantically. The surrounding order is not alphabetical, so it can move if you prefer it elsewhere.Section anchors on both
spec-urlswere verified against the published document. Both pages were built and checked in a local preview with no macro or link issues.Credit for the original pages goes to Sencer Öztüfekçi, the author of #44568, and to @hamishwillee for the review additions carried over from it.
Co-authored-by: Sencer Öztüfekçi senjer@hotmail.com
Co-authored-by: Hamish Willee hamishwillee@gmail.com
Related issues and pull requests
Fixes #44665
Relates to #44568