Add QUERY method description to HTTP methods index

[gomestai]

Description

Adds the HTTP QUERY method, defined by RFC 10008, to the HTTP request methods landing page.

The page currently lists the established HTTP request methods but does not include QUERY. This PR adds a short description and updates the safe/idempotent/cacheable method table.

Motivation

RFC 10008 defines QUERY as a safe and idempotent HTTP method that carries request content and returns the result of processing that content. It fills the use case where a request is read-only like GET, but the query input is too large or complex to fit comfortably in the URI.

Additional details

I added QUERY next to GET because both are safe, idempotent, and cacheable request methods. I avoided describing it as simply “GET with a body” and used wording closer to the RFC semantics.

I’m not sure whether a separate Web/HTTP/Reference/Methods/QUERY page and BCD/spec data should be added in the same PR or handled separately. Happy to adjust based on maintainer guidance.

Related issues and pull requests

None.

[github-actions]

Preview URLs (1 page)

• /en-US/docs/Web/HTTP/Reference/Methods

Flaws (2)

Found an unexpected or unresolvable flaw? Please report it here.

URL: /en-US/docs/Web/HTTP/Reference/Methods
Title: HTTP request methods
Flaw count: 2

• macros:
  • Macro httpmethod produces link /en-US/docs/Web/HTTP/Reference/Methods/QUERY which doesn't resolve
  • Macro httpmethod produces link /en-US/docs/Web/HTTP/Reference/Methods/QUERY which doesn't resolve

[hamishwillee]

Thanks @gomestai .

Thinking aloud:

• rfc10008 was only accepted a few weeks ago. As I understand it there isn't any specific browser integration as such. There is interest in allowing it to be specified in forms in Support QUERY method in form submissions whatwg/html#12594 - but it isn't clear whether that will happen - similar suggestions for other methods have existed for years.
• From the browser point of view I think you can use this now in a fetch request by specifying the method in your RequestInit or Request.method. Fetch only expects a name (you can use "CABBAGE" if you wanted) and because it isn't a CORS safelisted method the preflight should be handed for you.
• However I'm not sure about the rest of the internet, such as CDNs, caches, server frameworks such as Express, Django, whatever.
• Looking at the PR, yes, we will need a specific QUERY page.
• I am not sure about BCD yet. I don't think it gets a record because there is no direct integration.

Upshot, I'm going to see if I can get a little more information on this topic and get back to you. MIght not be very quick.

[hamishwillee]

@gomestai So I've had a short discussion on this.

• Browsers don't have explicit support (at least yet) so there is no need for a BCD update.
• Support is likely to be mixed. Most middlware and servers are unlikely to use a strict whitelist of methods and will likely just work, but caches may well need update.

What you have done is a first step - this really needs

• a page like GET (or or one of the other methods), with the right format and examples
  • This will need the spec-url key in the metadata to link to the spec, because there isn't a browser-compat key to use (as no BCD)
• A page for Allow-Query header.

This is a non-trivial bit of documentation. Are you willing to take it on. We could stop at this point if you think this is more than you are willing to commit. However it isn't all that useful at this point because until we have the page there is no spec link or detail on how it used.

[gomestai]

@gomestai So I've had a short discussion on this.

• Browsers don't have explicit support (at least yet) so there is no need for a BCD update.
• Support is likely to be mixed. Most middlware and servers are unlikely to use a strict whitelist of methods and will likely just work, but caches may well need update.

What you have done is a first step - this really needs

• a page like GET (or or one of the other methods), with the right format and examples

  • This will need the spec-url key in the metadata to link to the spec, because there isn't a browser-compat key to use (as no BCD)

• A page for Allow-Query header.

This is a non-trivial bit of documentation. Are you willing to take it on. We could stop at this point if you think this is more than you are willing to commit. However it isn't all that useful at this point because until we have the page there is no spec link or detail on how it used.

Thanks for the detailed guidance. I just saw this.

Yes, I’m happy to take this on. I’ll start on the method page and the Allow-Query header page tomorrow.