Add HTTP QUERY method and Accept-Query header references #44568
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,74 @@ | ||
| --- | ||
| title: Accept-Query header | ||
| short-title: Accept-Query | ||
| slug: Web/HTTP/Reference/Headers/Accept-Query | ||
| page-type: http-header | ||
| spec-urls: https://www.rfc-editor.org/info/rfc10008/#name-the-accept-query-header-fie | ||
| sidebar: http | ||
| --- | ||
|
|
||
| The HTTP **`Accept-Query`** {{Glossary("response header")}} indicates that a resource supports the {{HTTPMethod("QUERY")}} method and identifies the query format [media types](/en-US/docs/Web/HTTP/Guides/MIME_types) that it accepts. | ||
|
|
||
| `Accept-Query` is a structured field whose value is a list of media ranges (a media type that might include wildcards), each represented as a structured field string or token and optionally including structured field parameters. | ||
| The order of media types in the list is not significant. | ||
| Its value applies to every URI on the server with the same path, regardless of the URI's query component. | ||
|
|
||
| <table class="properties"> | ||
| <tbody> | ||
| <tr> | ||
| <th scope="row">Header type</th> | ||
| <td>{{Glossary("Response header")}}</td> | ||
| </tr> | ||
| </tbody> | ||
| </table> | ||
|
|
||
| ## Syntax | ||
|
|
||
| ```http | ||
| Accept-Query: <media-type>/<subtype> | ||
| Accept-Query: <media-type>/* | ||
| Accept-Query: */* | ||
|
|
||
| // Comma-separated list of media ranges in any order | ||
| Accept-Query: <media-type>/<subtype>, <media-type>/<subtype-2>, <media-type-2>/* | ||
| ``` | ||
|
|
||
| ## Directives | ||
|
|
||
| - `<media-type>/<subtype>` | ||
| - : A [media type](/en-US/docs/Web/HTTP/Guides/MIME_types) with a subtype that the resource accepts as `QUERY` request content, such as `application/json`. | ||
| - `<media-type>/*` | ||
| - : A media type that accepts any subtype. | ||
| For example, `image/*` corresponds to `image/png`, `image/svg`, `image/gif`, and other image types. | ||
| - `*/*` | ||
| - : Any media type. | ||
|
|
||
| ## Examples | ||
|
|
||
| ### Advertising supported query formats | ||
|
|
||
| The following response indicates that the resource supports `QUERY` requests with `application/x-www-form-urlencoded` or `application/sql` content: | ||
|
|
||
| ```http | ||
| HTTP/1.1 200 OK | ||
| Content-Type: application/json | ||
| Accept-Query: application/x-www-form-urlencoded, application/sql | ||
| ``` | ||
|
|
||
| ## Specifications | ||
|
|
||
| {{Specifications}} | ||
|
|
||
| ## Browser compatibility | ||
|
|
||
| Browser compatibility is not relevant for this header. | ||
| Browsers have no built-in handling of `Accept-Query`; it's up to the client sending `QUERY` requests to read the header and use it to select a supported media type for the request content. | ||
|
|
||
| ## See also | ||
|
|
||
| - {{HTTPMethod("QUERY")}} request method | ||
| - {{HTTPHeader("Accept")}} | ||
| - {{HTTPHeader("Content-Type")}} | ||
| - {{HTTPHeader("Content-Location")}} | ||
| - {{HTTPHeader("Location")}} | ||
| - {{HTTPStatus("415", "415 Unsupported Media Type")}} | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,116 @@ | ||
| --- | ||
| title: QUERY request method | ||
| short-title: QUERY | ||
| slug: Web/HTTP/Reference/Methods/QUERY | ||
| page-type: http-method | ||
| spec-urls: https://www.rfc-editor.org/info/rfc10008/#name-query-method | ||
| sidebar: http | ||
| --- | ||
|
|
||
| The **`QUERY`** HTTP method asks the target resource to process the request content in a safe and idempotent manner and return the result. | ||
| It is similar to {{HTTPMethod("POST")}} because the query is carried in the request content, but unlike `POST`, `QUERY` is explicitly {{Glossary("Safe/HTTP", "safe")}} and {{Glossary("Idempotent", "idempotent")}}. | ||
| This allows a `QUERY` request to be retried automatically without concern that it will cause additional changes to the target resource. | ||
|
|
||
| `QUERY` is useful when the query input is too large or complex for the target URI's query component. | ||
| The request's {{HTTPHeader("Content-Type")}} header is required and determines how the request content is interpreted by the target resource. | ||
|
Collaborator
There was a problem hiding this comment. Thanks @gomestai This is a good start. There are some important omissions with respect to the spec though.
If there ends up being too much in the top section we can add a Description section before the examples. We should look at all the examples, including those in the appendices and see what you can learn from them - might have some stuff worth capturing. Does that make sense? If it is too much, let me know and perhaps I can help you extend it
Collaborator
There was a problem hiding this comment. PS MDN is usually a human readable and website developer-centric version of the spec, needed because often specs are written primarily for browser vendors (in this case the spec is actually quite readable). In any case, we still don't just copy the spec - but we do need to copy the most important nuances of the features use in an accessible way. That's why I lean to starting with "this is mostly for implementing queries that might otherwise be too big to put in a GET", and then covering further details. This is also the first time there's been a new HTTP method in ages. So there will be eyes on this and we want to make sure we give users the head start they need to use it effectively.
Author
There was a problem hiding this comment. Thanks, this makes sense. I’ll expand the QUERY page to cover the missing pieces from the spec in a more developer-focused way: equivalent resources with Content-Location/Location, Accept-Query discovery and 415 handling, caching behavior, redirects, and conditional requests. I’ll also rework the intro so it doesn’t imply that QUERY is only for replacing long GET query strings, but presents that as one common use case. |
||
|
|
||
| <table class="properties"> | ||
| <tbody> | ||
| <tr> | ||
| <th scope="row">Request has body</th> | ||
| <td>Yes</td> | ||
| </tr> | ||
| <tr> | ||
| <th scope="row">Successful response has body</th> | ||
| <td>Yes</td> | ||
| </tr> | ||
| <tr> | ||
| <th scope="row">{{Glossary("Safe/HTTP", "Safe")}}</th> | ||
| <td>Yes</td> | ||
| </tr> | ||
| <tr> | ||
| <th scope="row">{{Glossary("Idempotent")}}</th> | ||
| <td>Yes</td> | ||
| </tr> | ||
| <tr> | ||
| <th scope="row">{{Glossary("Cacheable")}}</th> | ||
| <td>Yes</td> | ||
| </tr> | ||
| <tr> | ||
| <th scope="row"> | ||
| Allowed in <a href="/en-US/docs/Learn_web_development/Extensions/Forms">HTML forms</a> | ||
| </th> | ||
| <td>No</td> | ||
| </tr> | ||
| </tbody> | ||
| </table> | ||
|
|
||
| ## Syntax | ||
|
|
||
| ```http | ||
| QUERY <request-target>["?"<query>] HTTP/1.1 | ||
| ``` | ||
|
|
||
| - `<request-target>` | ||
| - : Identifies the target resource that will process the query when combined with the information provided in the {{HTTPHeader("Host")}} header. | ||
| This is an absolute path (e.g., `/path/to/resource`) in requests to an origin server, and an absolute URL in requests to proxies (e.g., `https://example.com/path/to/resource`). | ||
| - `<query>` {{optional_inline}} | ||
| - : An optional URI query component preceded by a question mark (`?`). | ||
| It helps identify the resource being queried; the query operation itself is defined by the request content and its media type. | ||
|
|
||
| ## Examples | ||
|
|
||
| ### Querying a collection | ||
|
|
||
| The following request queries a contacts collection. | ||
| The request content selects three fields, limits the response to ten results, and filters contacts by email address: | ||
|
|
||
| ```http | ||
| QUERY /contacts HTTP/1.1 | ||
| Host: example.org | ||
| Content-Type: application/x-www-form-urlencoded | ||
| Accept: application/json | ||
|
|
||
| select=surname,givenname,email&limit=10&email=%2A%40example.%2A | ||
| ``` | ||
|
|
||
| A successful response includes the query result in the response content: | ||
|
|
||
| ```http | ||
| HTTP/1.1 200 OK | ||
| Content-Type: application/json | ||
|
|
||
| [ | ||
| { | ||
| "surname": "Smith", | ||
| "givenname": "John", | ||
| "email": "smith@example.org" | ||
| }, | ||
| { | ||
| "surname": "Jones", | ||
| "givenname": "Sally", | ||
| "email": "sally.jones@example.com" | ||
| } | ||
| ] | ||
| ``` | ||
|
|
||
| ## Specifications | ||
|
|
||
| {{Specifications}} | ||
|
|
||
| ## Browser compatibility | ||
|
|
||
| Browser compatibility is not relevant for this method. | ||
| Browsers have no specific integration support for `QUERY`: it isn't sent for user-initiated actions like HTML form submissions, and browsers don't send it automatically in response to other headers or mechanisms. | ||
|
|
||
| Developers can issue a `QUERY` request using [`fetch()`](/en-US/docs/Web/API/Window/fetch). | ||
| NOte that because `QUERY` isn't one of the CORS-safelisted methods, cross-origin requests trigger a [CORS](/en-US/docs/Web/HTTP/Guides/CORS) preflight {{HTTPMethod("OPTIONS")}} request, the same as for other non-simple methods. | ||
|
|
||
| ## See also | ||
|
|
||
| - [HTTP request methods](/en-US/docs/Web/HTTP/Reference/Methods) | ||
| - {{HTTPHeader("Accept-Query")}} | ||
| - {{HTTPMethod("GET")}} and {{HTTPMethod("POST")}} | ||
| - {{HTTPHeader("Content-Type")}} | ||
| - {{HTTPHeader("Content-Location")}} and {{HTTPHeader("Location")}} | ||
| - {{HTTPHeader("Allow")}} | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
FYI the
/infoURLs are the ones that get updated to have a rendered description in the spec table. That hasn't been added yet but will be at some point. In any case though, we get to see the URL in this case, which is at least a little interesting.