We adopted HTTP QUERY as a draft. The RFC changed fourteen strings.

Search endpoints have always been squeezed between two verbs that each get half the job right.

GET /api/search?q=... is safe and idempotent, which is what a search is, so intermediaries are allowed to cache it, retry it and prefetch it. The cost is that every criterion has to fit in a URL. There is a practical length ceiling, and the whole thing is written down: in the access log, in the browser history, and unless you have set a referrer policy, in the Referer header of every outbound click made from the results page. On a platform whose search covers your colleagues' names, that is not an aesthetic concern.

POST /api/search gives you a body and takes away the semantics. A POST is neither safe nor idempotent by definition, so no cache will reuse a POST response for a later POST and no intermediary will retry one, and no reader of your API can tell from the verb that the call changes nothing. You end up writing "this POST does not modify anything" in your documentation, which is the tell that the verb is wrong.

QUERY is the missing corner: safe, idempotent, and it takes a body.

"The HTTP QUERY Method" is RFC 10008, Standards Track, from the IETF HTTP working group. It is short, and the contract is four properties:

What the spec deliberately does not do is define a query language. The body is whatever media type you declare. JSON for us, and the resource says which types it takes. QUERY is a transport for criteria, not a schema for them.

Which makes the goal a repair rather than a feature. The POST-for-reads pattern is everywhere: Elasticsearch's _search, every GraphQL read, every "advanced filters" call in every internal API, all of them safe operations wearing an unsafe verb because the body was worth more than the semantics. QUERY is the working group saying you should not have had to choose. Here is ours on the wire:

Two of those response headers are not ones an ordinary GET carries. They are the spec answering the problem the verb creates, and they are the subject of part two. Hold them. The /lunatech in front of the path is our tenant segment, added by a rewrite filter; the resource itself declares /api/search, which is how the rest of this post refers to it.

Our results page sends which entity families to search, a thematic filter of up to twenty ids, a difficulty filter and a row count. Twenty UUIDs is roughly 740 characters of query string before anything else is in it, and the interesting field is the one that is not a UUID: the search term, which on this platform is very often a colleague's name. A query string writes that into the access log, the browser history and the Referer of every outbound click. A body writes it nowhere.

The negative result is the part of this worth copying. Our first version was QUERY as a mirror of the GET: the same single field, moved into a body. It proved the plumbing and offered readers nothing, so nothing called it and we learned nothing from it. Today the two endpoints agree on the query text and on nothing else, and every criterion a query string should not carry lives on the body alone. The GET keeps the navbar type-ahead, correctly, because a two-character keystroke gains nothing from a body. A new verb earns its place only where it does something the stable endpoint cannot.

On Quarkus with Quarkus REST, the entire binding for a brand new HTTP method is one file, QUERY.java:

That is the same mechanism JAX-RS uses to define @GET and @POST themselves. No extension configuration, no filter, no route table. Annotate a resource method with it and the chain works end to end:

The browser side is one line of fetch, with one trap in it: pass the method uppercase. The fetch spec only normalises casing for the standard verbs, so method: 'query' goes out lowercase on the wire and a case-sensitive server match will not find your endpoint.

One annotation file, one request DTO, one handler, one client function. If you have been putting off trying QUERY because you assumed the framework would fight you, it will not.

Which is the whole of the cheap part. Everything below is what it cost.

Adopting an unpublished draft has an obvious risk, and we paid for it up front. The endpoint went behind a feature flag that is off by default, opted into per environment, and on in production. The old GET stayed exactly where it was. The revert was written down before it was needed, in two versions, a cheap one and a thorough one. Every new type we added carried an @Experimental marker saying it might change or disappear with the draft.

Then the draft became RFC 10008, at the revision we had built against, and we got to settle the account. What did publication demand of us?

Nothing that runs. No rework, no migration, no behaviour change, not one line of logic. The section numbers we cite in comments are the section numbers the RFC publishes. What it retired was fourteen strings across seven files: the word "draft" in a handful of javadoc lines, four @Experimental messages, three frontend comments, and two OpenAPI descriptions that told API readers this was a draft method.

Fourteen strings is the entire measurable cost of the risk we were managing. Which is worth sitting with, because the rest of the work was substantial, and none of it was about the spec's status:

So the hedge was cheap, and that is the useful finding rather than a boast: spec risk is the cheapest risk on the list and the easiest to feel diligent about managing, while the expensive ones sit in your infrastructure and in how carefully you read the document. Two of the six lines above are not costs of adoption at all. They are the cost of not reading.

Moving a query into a body takes it out of the URI, and in HTTP the URI is identity. Everything that was addressable because it lived in a query string stops being addressable: bookmarking, the back button, sending a colleague your search, and every cache in the path. The spec knows, and answers it in four subsections of section 2, with a fifth mechanism in section 3.

We hand-rolled two of those before reading them. Both have since been replaced by the spec's version.

Capability discovery. We used to learn whether a deployment took the verb by firing a QUERY and interpreting the failure, at a cost of one wasted request per page load everywhere the feature was off. Accept-Query is the designed answer, and it costs a header: our GET response now advertises Accept-Query: application/json when the structured search is available, so the type-ahead's very first call tells the client whether the structured path exists, on a request it was making anyway. One subtlety survives the fix, and it is the reason the fallback below did not get deleted along with the probe: only the header's absence is conclusive. A proxy that strips unknown methods forwards the GET carrying the header perfectly happily, so an origin server advertising support tells you nothing about what sits in front of it.

Addressability. We solved it by taking the term out of the URL entirely and holding it in client state, which is private and unbookmarkable, and which cost us the back button within a day. Location gets both properties at once: the QUERY response now names GET /api/search/{token}, the equivalent resource of section 2.2, an opaque server-minted URI that is meaningless to a reader of your history or your logs, works as a link, survives a reload, and is cacheable by every cache that already exists. Which also retires the argument that QUERY's cacheability is theoretical. Caching the QUERY itself is theoretical. Caching the GET it hands you works today.

Somewhere in front of your application there is a load balancer or reverse proxy, and some of them implement HTTP by allowing the verbs they know and rejecting the rest. If yours does that, your endpoint answers 405 or a proxy error page, and no local testing will have told you, because your development machine has no proxy in it.

This is the risk publication does not touch. A published RFC does not oblige anybody's infrastructure to have heard of it.

The technique that answers it costs nothing: gate the endpoint behind a feature flag that answers in your own error format, then fire a request at production with the feature still off.

That 501 is the good news. Our gate is a post-matching JAX-RS filter, so it runs after routing, after authentication and after the permission check, which means a body naming our own error code can only have been produced inside the JVM on a matched resource method. And Sozu-Id names Sozu itself, the Rust reverse proxy Clever Cloud runs, stamping the response on its way out.

Do not gate a release on a piece of infrastructure you cannot inspect. Make the client stop caring about the answer instead. The whole of it, in lib/api/search.ts, hangs off one three-state verdict:

The first structured search of a page load goes out as QUERY. If the transport refuses it, the verdict flips to unsupported and every later search on that page is a plain GET. Worst case on a hostile proxy is one wasted request per page load, and the type-ahead never pays even that, because a two-character keystroke gains nothing from a body and stays on the GET where it belongs.

That is what let us ship before we had the measurement above. It is also, on a deployment whose proxy does refuse the verb, the permanent operating mode, which is worth designing as a real state rather than an error path.

When you fall back between transports, you need a predicate that separates "this path does not work" from "this path worked and told you no". Those look alike in a status code and are opposites in meaning.

405 is a rejected method. 501 is either our own gate or a proxy that does not implement the verb. Both mean stop trying.

400 is where it goes wrong. A 400 can be our own bean validation telling the reader their search term is too long, and it can equally be a proxy that could not parse the request line. Treat that validation 400 as a refused verb and you have silently dropped the reader's filters for the rest of their session, over a typo. Nothing crashes, nothing logs, the filters just stop working.

So the predicate that decides whether to fall back reads the body, not the status:

Our validation errors are RFC 9457 problem details and carry a machine-readable code. A proxy that choked on the request line answers something else entirely. Anything that is neither a refusal nor a validation failure is rethrown, because a 403 has to reach the caller as a 403.

Report a criterion as unapplied when it ran against incomplete data, not only when it was dropped. And do not report one that changed nothing. Both halves came from getting it wrong.

The fallback path can honour some criteria and not others: a GET carries a query string, so the entity families, the difficulty filter and the row count can be applied to the response after the fact, while a thematic filter cannot, because a result row does not carry its thematics. We applied the difficulty filter client-side over the rows the GET returned, and the GET returns at most five per family. Five hard trainings at the top and forty easy ones behind them, filter for easy, get an empty page. The filter ran, and correctly. It was applied to the wrong universe and reported as applied. A filter over a truncated window is worse than a filter that was skipped, because skipping is something you can tell the reader about.

The other half: our banner fired on every search, because "the client asked for twenty rows and the fallback returns five" is true whether or not anything was actually cut off. A warning that appears every time is a warning nobody reads on the day it matters.

Moving criteria into the body buys nothing if your own entry path writes them into the address bar, which ours did: the navigation bar handed off to /search?q=sec and the results page read it back.

Rank the surfaces before you fix anything, because they are not equal. The Referer was already covered, since we send Referrer-Policy: strict-origin-when-cross-origin and an outbound click therefore gives a third party our origin and nothing else. The access log barely saw it, because the hand-off is a client-side route change in a static export and never reaches the server. What was genuinely exposed was the browser history, on a machine that may be shared or syncing.

What the address bar carries now is the section 2.4 token, and the choice inside it is the one worth stating: the token is the criteria encrypted, AES-256-GCM, rather than signed. A signed-but-readable token is the more ordinary thing to build and it would have put the search term straight back into the history and the log that the body exists to keep it out of. A server-side store would have moved it into our database instead. So: opaque to everyone but the server, seven-day expiry then a 410 that says so, and no capability of its own, since the endpoint behind it gates on the same permission as every other read. A token minted in another organisation and a token that never existed share one 404, because telling them apart would let a URL pasted into the wrong tenant prove it was a real search somewhere else.

One deployment detail that is ours rather than the spec's: the browser-side address is ?s=<token> while the API side is a path segment. Our frontend is a static export in which the tenant is the only dynamic segment, so /search/<token> is not a route that can exist. The token is opaque either way, and history, reload, back, forward and sharing all work on a URL that says nothing about what was searched.

Every item below was true while QUERY was a draft and is still true now that it is a standard. None of them is spec risk, and all of them outlast it.

Give the verb a feature the stable endpoint cannot serve, or do not adopt it. Then, in the order the problems arrive:

WeLearn is our internal platform, but the front door is open. welearn.lunatech.com drops you into a demo tenant in one click, no account and no email, wearing a made-up colleague's shoes. Search for something with the network tab open and you will watch the verb go out.

Measured against production on 8 September 2026, against the text now published as RFC 10008. Sozu behaviour can change; re-check before relying on it.