Planning for HTTP QUERY method (RFC 10008)

[Kevsy]

A new HTTP method, 'QUERY', has been specified recently in RFC 10008. The relevance for CAMARA is that it can change the guidance for POST or GET for transferring sensitive or complex data. The RFC positions QUERY as being an improvement on using POST for such scenarios (including performance gains).

To decide if CAMARA should adopt this, I believe there are four considerations:

1. Security review (IETF will have performed a thorough review as part of the standards process, but no harm in checking)
2. Support by web servers and proxies (work-in-progess implementations are tracked here)
3. The non-backward-compatibility impact to CAMARA OAS specifications
4. Predictable, consistent fallback if QUERY is attempted but not supported (e.g. what should be the behaviour following a 405 Method Not Allowed for an attempted QUERY?)

So this seems a question for a future release (maybe Spring 28?) to give the ecosystem time to grow and test the benefits and interoperability. One approach may be for new APIs (from a certain date) to implement QUERY, and gradually deprecate the POST workaround for existing APIs.

A summary of the the RFC Introduction follows...

This specification defines the QUERY method for HTTP. A QUERY requests that the request target process the enclosed content in a safe and idempotent manner and then respond with the result of that processing. This is similar to POST requests, but QUERY requests can be automatically repeated or restarted without concern for partial state changes.

A common query pattern is:

GET /feed?q=foo&limit=10&sort=-published HTTP/1.1
Host: example.org

However, when the data conveyed is too voluminous to be encoded in the request's URI, this pattern becomes problematic:

• size limits often are not known ahead of time because a request can pass through many uncoordinated systems (but note that Section 4.1 of [HTTP] recommends senders and recipients to support at least 8000 octets),
• expressing certain kinds of data in the target URI is inefficient because of the overhead of encoding that data into a valid URI,
  request URIs are more likely to be logged than request content and may also turn up in bookmarks,
• encoding queries directly into the request URI effectively casts every possible combination of query inputs as distinct resources.

As an alternative to using GET, many implementations make use of the HTTP POST method to perform queries, as illustrated in the example below. In this case, the input to the query operation is passed as the request content as opposed to using the request URI's query component.

A typical use of HTTP POST for requesting a query is:

POST /feed HTTP/1.1
Host: example.org
Content-Type: application/x-www-form-urlencoded

q=foo&limit=10&sort=-published

In this variation, however, it is not readily apparent -- without specific knowledge of the resource and server to which the request is being sent -- that a safe, idempotent query is being performed.

The QUERY method provides a solution that spans the gap between the use of GET and POST, with the example above being expressed as:

QUERY /feed HTTP/1.1
Host: example.org
Content-Type: application/x-www-form-urlencoded

q=foo&limit=10&sort=-published

As with POST, the input to the query operation is passed as the content of the request rather than as part of the request URI. Unlike POST, however, the method is explicitly safe and idempotent, allowing functions like caching and automatic retries to operate.

Further reading (including performance gains through caching) here.