nginx will proxy the new HTTP QUERY method. It will never cache one.

The IETF published RFC 10008 back in June, and it adds a method to HTTP called QUERY. The short version is that it's a GET that's allowed to carry a body, so it's safe and idempotent like a GET, and it's cacheable, with the extra rule that whatever you put in the body has to end up in the cache key. The use case is the read whose parameters won't fit sensibly in a URL. Right now we all send those as POST and quietly accept that nothing downstream will ever cache them.

I've been curious whether any of the surrounding machinery is ready for it, so I spent a morning finding out. I wrote a search API that refuses every method except QUERY, put it on a small box in Frankfurt, and pointed ten language models at it to see whether they could produce a working client.

My assumption going in was that the models would be the weak link. That turned out to be wrong, and the thing that actually broke was the proxy.

The API

It searches the RFC index, which seemed like a fair dataset to pick given the circumstances. There are 9,836 entries in it. The filter document is exactly the shape RFC 10008 describes: optional substring matches on title and author, a year range, a list of acceptable statuses, a sort key, a limit.

Send it a GET or a POST and you get a 405 back, with an Allow: QUERY header and a body that names whichever method you tried. That rigidity is deliberate, because a server willing to also accept POST would have quietly absorbed every interesting failure instead of showing it to me.

$ printf '%s' '{"title_contains":"QUERY","limit":1}' \
  | curl -s -X QUERY --data-binary @- -H 'Content-Type: application/json' http://.../rfcs
{
  "total_matched": 21,
  "returned": 1,
  "results": [
    { "id": "RFC10008", "title": "The HTTP QUERY Method", "year": 2026, ... }
  ]
}

When the prompt names the method, everything works

My first prompt was explicit about it: this endpoint takes one method, QUERY, from RFC 10008. Each model got a URL path of its own so that the server's log could tell me who sent what, and I ran every generated program rather than reading it and forming an opinion.

Eight models were reachable on my account. Three families came back 403 on this tier and one returned a 400, which is a lesson about inference platforms rather than about HTTP, so I left it alone.

Every one of the eight produced a program that sent a QUERY and printed the five RFCs I'd asked for. Nobody hedged, nobody fell back to POST. Here's the log:

QUERY /rfcs/llama-4-maverick        QUERY /rfcs/deepseek-v4-pro
QUERY /rfcs/mistral-3-14b           QUERY /rfcs/gemma-4-31b-it
QUERY /rfcs/glm-5-3-flash           QUERY /rfcs/openai-gpt-oss-120b
QUERY /rfcs/openai-gpt-oss-20b      QUERY /rfcs/minimax-m2-5

Python helps here. urllib.request.Request(url, data=body, method='QUERY') is the whole trick, the standard library has never cared what you put in that argument, and all eight found it without visible effort.

When it doesn't, nobody guesses right

The version I actually wanted was the one where the method never comes up. So I rewrote the prompt the way a colleague would throw it at you in passing: here's a URL, here are the fields, it takes JSON, write me a client.

All eight sent POST.

None of them tried an OPTIONS request first. None of them treated the method as an open question at all, which is reasonable, because a JSON search endpoint has been POST for fifteen years and that prior is earned.

Two were cleverer than the rest about what happened next. deepseek-v4-pro and openai-gpt-oss-20b had both written code that caught the 405, looked at the Allow header while running, and retried using whatever it named. Neither was asked to. You can watch it in the log:

/r1/deepseek-v4-pro        POST -> QUERY
/r1/openai-gpt-oss-20b     POST -> QUERY

Given the answer, half of them take it

Next I pasted each model the exact failure it had caused: status line, headers with Allow: QUERY, OPTIONS among them, and the JSON body spelling out the method it should have used. Fix your program.

Four out of eight, from a response that hands over the answer in a header.

The llama attempt is the one I keep thinking about, because it changed the method correctly and then url-encoded all the filters into the query string and sent an empty body, which throws away the single reason the method exists. Mistral's is blunter. The server said Allow: QUERY and it went with GET, which the same server had refused thirty seconds earlier.

nginx will carry a QUERY, and will never cache one

This matters more than anything the models did.

Proxying is fine. Drop nginx in front of the API and every request goes through untouched. The trouble starts when you try to cache, which RFC 10008 explicitly permits:

$ nginx -t
nginx: [emerg] invalid value "QUERY" in /etc/nginx/sites-enabled/default:9
nginx: configuration file /etc/nginx/nginx.conf test failed

proxy_cache_methods takes GET, HEAD and POST. You can't extend the list, and asking for anything else stops the server from starting.

The workaround anyone would try next is rewriting the method upstream with proxy_method POST and declaring POST cacheable. That fails too, and the reason is subtle: nginx tests proxy_cache_methods against what the client sent, not what it forwards. I checked by counting the requests that actually arrived at the backend, holding the config and the body constant and varying only the method on the wire.

Sent as POST, three of the four never got past nginx. Sent as QUERY, the cache sat there doing nothing, and there isn't even a cache status header to hint that it declined.

Which leaves us somewhere silly. The method designed to be cached can't be, by the proxy most of the internet runs, while the method that isn't supposed to be cacheable is.

What I got wrong on the way

Three things, and I nearly published the second one as a result.

My server read Content-Length and stopped there. Node's http module doesn't set Content-Length for a method it has no opinion about, and reaches for Transfer-Encoding: chunked instead, so my server found an empty body, replied anyway, and left the chunks sitting unread in the socket. Whatever came next on that keep-alive connection parsed as rubbish, and node told me Parse Error: Expected HTTP/, RTSP/ or ICE/. I lost twenty minutes to believing node couldn't send a QUERY. It can. If you write one of these servers, handle chunked bodies.

To work out which method each program used, I grepped its source for method names. That reported three models picking GET in the no-hint round. The server log said all eight sent POST, every time. My regex had matched the word inside a comment or an unused error branch. The figure in this post comes from the log, because the log is a record of what happened and my grep was a record of what I assumed.

Then there's my own Content-Location header, which advertises /rfcs?limit=1&title_contains=QUERY. RFC 10008 offers that header as the GET-able equivalent a cache can hold onto. Mine answers 405 to a GET, so it's pointing at a door that doesn't open. I only spotted it while checking something unrelated.

Run it yourself

The server is roughly a hundred lines of standard library Python. The client is four:

import json, urllib.request
body = json.dumps({"title_contains": "HTTP", "year_from": 2020, "limit": 5}).encode()
req = urllib.request.Request(URL, data=body, method="QUERY",
                             headers={"Content-Type": "application/json"})
print(json.load(urllib.request.urlopen(req))["total_matched"])

For the nginx behaviour, put any backend behind proxy_cache with proxy_cache_methods POST, send one body four times as POST and four times as QUERY, and count arrivals at the backend instead of reading headers:

for i in 1 2 3 4; do curl -s -o /dev/null -X QUERY --data-binary '{"a":1}' http://localhost/; done
for i in 1 2 3 4; do curl -s -o /dev/null -X POST  --data-binary '{"a":1}' http://localhost/; done

I reached the models through DigitalOcean's inference endpoint, and the API sat on a 1-vCPU droplet in Frankfurt, so nothing in the model experiment went over loopback.

What to do about it

Clients are ready. Python, curl and node all send QUERY today without any ceremony, and the models writing your integration code will get it right as soon as your documentation mentions it. Don't skip that step. Eight out of eight assumed POST, and the only two that arrived at QUERY on their own got there by reading a 405 mid-flight.

It's the middle of the stack that will disappoint you. Count what reaches your backend before believing anything about caching, because nginx fails at this silently, with no error and no header, just every request sailing through. I only noticed because I gave up on headers and started counting.

And if caching is your reason for wanting QUERY at all, look at your proxy before you commit to the protocol. On nginx as it stands you can keep sending POST and cache it, or you can put something else in front. Neither is what the RFC had in mind, and a method nothing will cache is POST with better manners.