Tykok

Posted on Jun 28

The new HTTP method : QUERY

#programming #http #restapi #backend

You work with REST APIs? You know GET, POST, PUT, DELETE...

But did you know that a new HTTP method was standardized in June 2026? It's called QUERY and it solves a problem developers have been working around for 16 years.

It's the first new standard HTTP method since PATCH (2010). Yes, you read that right: 16 years without major innovation in HTTP verbs.

The `GET` Method Problem

You want to create an endpoint to retrieve order information from your backend and add filters. You use a GET method for this endpoint because you're retrieving a resource and it’s the REST standards.

You add different parameters to the URL to filter results and return only orders that match your search:

GET /orders?select=surname,givenname,email&limit=10&match="email=*@example.*"

Problems:

URLs have size limits (often 8000 characters max)
Parameters are visible in logs (security issue)
Impossible to make complex queries (advanced filters, SQL queries, JSONPath)
Complex to encode correctly

What About Using `POST` instead?

To address the different problems with GET requests, you might turn to a POST request:

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

select=surname,givenname,email&limit=10&match="email=*@example.*"

Problems:

POST is not idempotent → if the network drops, you can't safely replay the request
No standard HTTP caching
Proxies don't know if it's safe to reject/retry
Each framework implements its own "safe POST" system

The Solution: `QUERY`

QUERY gives you the best of both worlds:

QUERY /orders HTTP/1.1
Host: api.example.org
Content-Type: application/x-www-form-urlencoded
Accept: application/json

select=surname,givenname,email&limit=10&match="email=*@example.*"

Advantages:

No URL size limit – The request body can contain SQL queries, JSONPath, or complex filters of unlimited size
Idempotent – Execute the request 10 times = execute it once

What is Idempotence?

An operation is idempotent if calling it multiple times produces the same result as calling it once.

Concrete examples:

✅ GET /users/123 (idempotent) → 1 call = 10 calls = same data

✅ QUERY /users (idempotent) → replaying = same result

❌ POST /users (NOT idempotent) → 1 call creates 1 user, 2 calls create 2 users

Why is this crucial? If the network drops, you can safely replay without creating duplicates or corruption.

Cacheable – Proxies, CDNs, browsers can cache the response (like GET)
Request body – Send complex data in the body (like POST), not in the URL
Safe – Never modifies server state (read-only)
Safely replayable – If the network drops, you can replay the request with confidence
URI for the request – The server can create a permanent URL to replay the same request

URI for the Request vs. URI for the Result

With classic POST (URI of result):
POST /orders → 200 OK

Content-Location: /results/xyz789
With QUERY (URI of the request):
QUERY /orders → 200 OK

Location: /saved-queries/42
The magic: Replaying /saved-queries/42 re-executes the same SQL/JSONPath query with updated data.

Concretely:
# Later...

GET /saved-queries/42

# → The server re-executes the original SQL query

# → You get fresh results

What's it useful for:

Share a query (send the link to a colleague)
Bookmark a search
Cache the query (not just the results)
Replay periodically without resending the body each time

Thanks to QUERY, we finally have functional HTTP caching for complex requests. Proxies, CDNs, and browsers can now cache requests with a body. This is huge for performance.

We also get an evolution in REST API design. Instead of:

GET /api/users/active
GET /api/users/inactive
GET /api/users/premium

You now have:

QUERY /api/users

With a single endpoint, it's easier to maintain, secure, and monitor.

Summary: GET vs POST vs QUERY

Feature	GET	POST	QUERY
Safe	✅ Yes	❌ No	✅ Yes
Idempotent	✅ Yes	❌ No	✅ Yes
Body allowed	❌ No	✅ Yes	✅ Yes
Cacheable	✅ Yes	⚠️ Complex	✅ Yes
Safely replayable	✅ Yes	❌ Risky	✅ Yes
URI for the request	✅ By default	❌ No	✅ Optional

Conclusion

QUERY finally gives us a solution for executing complex requests. It's a "small" change with a big impact. This new method solves a real problem that developers have been working around for years.

Moreover, this method was just standardized recently (June 2026), so it will take a while before it's truly adopted.

⚠️ Deployment Status

✅ Standardized: RFC 10008 (June 2026)
⏳ Implementation: Very few servers/clients support it yet
🚀 Timeline for adoption: Probably 2027-2028

Before using it in production, wait for implementations to become more widespread. For now, it's mainly important to understand the concept and keep it in mind for your future API architecture.

Next Step: QUERY in Practice

This article covers the theory and key concepts of QUERY. But how do you use it practically?

In a future article, I'll explore practical implementation of QUERY with a REST API, showing how to build a REST API that supports this new HTTP method and how to integrate it into a real-world architecture.

Stay tuned! 🚀

Top comments (10)

Ravavyr • Jul 8

ok, i don't see the reasoning for it.

character limits are large, you should be able to comfortable make GET requests all day with no issue.
POSTs creating duplicate entries is just bad code handling, if you use a nonce that problem goes away.

We also have PUT and DELETE that no one ever uses since you can pretty much accomplish all of them with POST just the same.

It just feels like one more thing only some devs will use, and newbies will get confused by and in the end we'll just be doing GET and POST anyway.

Just my 2 cents.

Matej • Jul 9 • Edited

You can do everything with POST alone. You can retrieve data, create new entities, update stuff or delete them. Hence I suggest we remove all HTTP verbs including POST, since it can be implied. Problem solved.

On the other hand we may want some semantics, so things clearly show their intent from afar without having to delve into codebase or descriptions. That's why any of my OAS, have very few POST requests, one for every entity that allows the client creation. Then I also seldom use PUT, because there are rare cases, where I intend to update an entity by replacing it whole. I used to create a lot of update forms where you'd change as many values as wanted in GUI and then explicitly PUT them by pressing the Save button. Nowadays, I auto-save most inputs on blur (the opposite of focus), so updates are way more surgical. Hence most of my updates use PATCH request to update existing entity's properties or whatever state is in question. DELETE is self explanatory in all its glory. Admittedly I have never gotten around to try to deeply understand the use cases for HEAD, CONNECT, OPTIONS and TRACE for me, so all that's left is GET. I love using it without query params, but when those are needed, I always disliked how GET is the odd one out of all the HTTP verbs. That is all to say, I am thrilled for QUERY to have become a new standard for this usecase.

As for you, it's simple... Just don't use it.

Edit: I by no means mean that QUERY should replace GET+queryParams everywhere. While it will do so in my OASs, I think it is absolutely essential to keep it, so we can for example share links with already filtered or ordered results.

Tykok • Jul 9

Thanks for sharing your thoughts!

I actually agree with a few of your points. For the vast majority of APIs, GET and POST are enough, and I don't expect QUERY to suddenly become the default method everyone uses.

The motivation behind QUERY isn't really about URL length limits. It's more about HTTP semantics. Sometimes you need to perform a read-only operation, but the query payload is too complex or structured to fit naturally in a query string. Today, many APIs solve this by using POST, but that comes with trade-offs: the request no longer clearly expresses that it's safe and idempotent, which can affect caching, intermediaries, tooling, or simply make the API less self-descriptive.

Regarding duplicate POST requests, I completely agree that good API design (nonces, idempotency keys, etc.) solves that issue. My point wasn't that QUERY replaces those mechanisms, but that it allows read operations to remain read operations instead of overloading POST for everything.

Whether QUERY sees widespread adoption is another question. It may end up being a niche method, just like PATCH took years to become common. But I still think it's an interesting addition because it fills a gap in the HTTP method semantics rather than introducing a completely new capability.

Thanks again for the feedback.

Karlatt Houaok • Jul 9 • Edited

This is a very important and valid point you are raising . Semantics .

Everyboby forgets that the web SHOULD be semantic in all aspects ,from verbs to https responses, to json content.
Just to say, Transformers self-attention and back-propagation mechanisms are ALL about semantic. At a time when everybody speaks with less and lesser words, which narrows the semantic fields of idea themselves, I think this is one of the most important points we should be aware of.
And, lazy as we are, we should be constrained to keep a little bit of order and structure, ,not to speak about meaning, in the fundamental units we build our tools with.

Saying that "good design replaces this or that", is like saying "why do I need a ribbon meter, my personal "measuring wood stick" allows me to measure anything at the millimeter scale without error , because I KNOW that its 10.2 centimeters long . Happy for you ! But how about crafting a measuring tool that is a hundred times simpler to use and universally usable ?
And there's a big contradiction between speaking of POST Tunnelling (BTW , why use GET also? POST can do the job) and telling that "good API design (BTW, using nonce is a bandage on a wood leg,a bad practice that exists precisely because of missing HTTP verbs like QUERY) or whatever can do the job. We are using some very bad practices by habit, because once this was the only way to do some special operations, this is a very bad reason to continue to use them when they can be replaced by clean , proper tools that are taking all the edge cases into account.
Proper semantics allow for good understanding, good architecture,strong and reliable structure, and,of course,in an universal way : everybody needs semantics (semantics just means "sense", so we need it more and more in our non-sense society.Or we can just say : Hey, let's use the word "cow" for anything that makes milk, it would be simpller, and then we should be able to understand that a "little furry cow with orange tail" is a fox, right ?
Semantics are foundational , and everybody shouldn't have to build its own rules if they don't exist, especially in the web field. Semantics is what allows convention over configuration....on this subject, just make a little parsing test (with ANY parser, you can build one if you want) to measure only perfs between a React generated page (after rendering and hydration, if not you don't have HTML, only JS) with 213 nested spans and divs , and the same properly written semantic web page (remember , HTML5 has more than one hundred tags , and we use ...5 at most)!.
Not to speak about accessibilirty, which is just impossible without any semantics .

So , as we badly need semantic structures , we should be happy and grateful to the people who work on any form of Semantics standards.First, it can be very boring and hard as an everyday job, but this could only lead us to use more universal tools and understand each other naturally , without having to read the docs for any bit of information we need.