The new HTTP QUERY method (RFC 10008): What it is and why it fills the gap between GET and POST

Posted by

   

For years, web API designers have faced a frustrating trade-off: when it came to retrieving complex data, the traditional system showed its limitations. With the official publication of RFC 10008 by the IETF (the body that defines internet standards), a new official HTTP method has been introduced: QUERY.

This article analyzes in detail what this method is, clarifies what "idempotence" means without beating around the bush, reviews the current state of the art, and shows differences and practical examples compared to the classic POST.

🔗 Do you like Techelopment? Check out the website for all the details!

1. The Problem: The Void Between GET and POST

Before the introduction of QUERY, options for querying a server were essentially twofold, both imperfect for certain situations:

  • GET (The safe and cacheable method, but without a body): It is ideal for reading data, can be cached, and repeating it is safe. However, it does not support a request body. All parameters must pass through the URL (the query string). This creates huge problems when sending complex filters, nested JSON structures, or very long queries, as URLs have practical length limits (imposed by browsers or servers).
  • POST (The method with a body, but unsafe): It allows sending any amount of data in the request body. The problem is that POST is semantically designed to modify server state (create resources, make payments, register users). Consequently, POST requests are not idempotent and cannot be safely cached by browsers or intermediate proxies. Repeating a POST by mistake (e.g., due to a network timeout) could mean duplicating an operation or altering data.

The Solution: QUERY

The QUERY method combines the best of both worlds: it takes the body-carrying structure of the POST and combines it with the safety and idempotence of the GET.


2. What Exactly Do "Idempotent" and "Safe" Mean?

Many technical articles use these terms taking for granted that everyone knows them. Let's simplify to the utmost:

  • Safe: Means that the request does not modify the server state. When you make a QUERY request, you are simply asking the server: "Read some data for me by processing these criteria." The database is not altered, no records are created, and no emails are sent. It is a logical read-only operation.
  • Idempotent: Means that executing the same request once or a hundred consecutive times produces the exact same identical effect on the server. Since the request does not change the state, repeating it infinitely will not result in unwanted side effects.

Why Is Idempotence Crucial?

Because QUERY is idempotent and safe, network clients, load balancers, and CDNs (Content Delivery Networks) can automatically retry a failed request (for example, if the connection drops) without fearing to cause damage or alterations. Moreover, unlike POST, responses to a QUERY method can be cached, drastically improving API performance.


3. State of the Art: Can It Already Be Used?

The answer is: Yes, but with proper infrastructural precautions.

  • Standardization: RFC 10008 is officially an IETF Proposed Standard. It is no longer a theoretical draft, but a ratified standard.
  • Support in Languages and Backends: Many ecosystems have moved quickly. Environments like Node.js (in the http module) and Go (thanks to the flexibility of net/http) natively support or handle custom methods like QUERY without issues. Modern backend frameworks (such as in .NET 10 or similar ecosystems) are integrating out-of-the-box support.
  • The Bottleneck (Browsers and Middleware): At present, no major browser natively implements sending a QUERY method via JavaScript fetch/axios (usually falling back to POST or GET). Furthermore, older Web Application Fires (WAFs), reverse proxies, or corporate security filters might not yet recognize the QUERY verb, mistaking it for an error or blocking it if not updated.

4. Practical Examples: POST vs QUERY Compared

Imagine having to develop an e-commerce system where the user can filter an immense product catalog using advanced criteria expressed in JSON (categories, price range, multiple dynamic attributes).

Traditional Approach with POST

Historically, to bypass the query string length limit of a GET, developers used a POST disguised as a search:

POST /api/products/search HTTP/1.1
Host: api.store.com
Content-Type: application/json

{
  "category": "electronics",
  "price_range": { "min": 100, "max": 500 },
  "tags": ["wireless", "bluetooth"],
  "sort": "popularity"
}

The problems with this approach:

  1. No Caching: Since the method is a POST, no intermediate cache (like Cloudflare or the browser) will save the result. Every single identical search will repeat the heavy computation on the database.
  2. No Automatic Retry: If the connection drops while the POST request is in transit, the client doesn't know if the server received the data, and it is risky to repeat it automatically.
  3. Wrong Semantics: You are telling the server to "create or process something" (POST), whereas you only want to "read" filtered data.

The New Approach with QUERY

Here is how the exact same call changes by adopting the QUERY standard (RFC 10008):

QUERY /api/products HTTP/1.1
Host: api.store.com
Content-Type: application/json
Accept: application/json

{
  "category": "electronics",
  "price_range": { "min": 100, "max": 500 },
  "tags": ["wireless", "bluetooth"],
  "sort": "popularity"
}

The immediate advantages:

  1. Caching Enabled: The server response can be cached safely, just like a GET would do, greatly lightening the load on the database for frequent searches.
  2. Idempotence and Safety: If the network flickers, the client knows it can repeat the QUERY request as many times as it wants without running the risk of altering the system state.
  3. Clean Separation of Concerns: The URI (/api/products) identifies the main resource, while the request body defines the filtered view you wish to obtain, without polluting the URL with unreadable or excessively long parameters.

Furthermore, the standard introduces dedicated headers like Accept-Query to allow the server to declare which query formats it supports, making content negotiation extremely clean.


5. Conclusions

The HTTP QUERY method is not a mere stylistic whim, but the formal resolution of an architectural anomaly that lasted for decades in the HTTP protocol.

Although browser-side and proxy adoption will take time to complete, understanding and integrating QUERY into your server-to-server APIs or modern backends represents a fundamental step toward writing cleaner, higher-performing, and semantically correct code.



Follow me #techelopment

Official site: www.techelopment.it
facebook: Techelopment
instagram: @techelopment
X: techelopment
Bluesky: @techelopment
telegram: @techelopment_channel
whatsapp: Techelopment
youtube: @techelopment