HN Debrief

The new HTTP QUERY method explained

  • Infrastructure
  • APIs
  • Web
  • Standards

The post walks through the new HTTP QUERY method, a standardized way to send read-only requests with a body. It is aimed at cases like complex searches, filters, and GraphQL-style reads where query strings are too cramped or awkward, but POST has the wrong semantics because it signals an unsafe operation and is poorly cached by default. The practical pitch is simple: QUERY is "GET with a body" made explicit, so intermediaries and tooling can treat it as safe and idempotent instead of guessing.

If your APIs currently use POST for search, filters, or GraphQL reads, QUERY is worth tracking because it gives cleaner semantics and a better path for tooling and caching over time. Do not plan on immediate browser, proxy, CDN, or WAF support, and design an explicit fallback path from QUERY to POST.

Discussion mood

Cautiously positive about the need, skeptical about the rollout. Most people liked having an official safe read method with a body because GET-with-body breaks in the wild, but many doubted that a new verb will get broad support quickly across browsers, proxies, CDNs, WAFs, and enterprise appliances.

Key insights

  1. 01

    GET bodies already fail in production

    The case for QUERY is not theoretical. Browsers block or limit GET bodies in fetch, servers and frameworks may ignore them, and infrastructure like CloudFront or strict WAF setups can reject them outright. That turns "just use GET with a body" into a fragile private convention that breaks as soon as traffic crosses a different stack.

    Audit any read-style endpoint that currently relies on GET bodies or overloaded POST. If traffic crosses browsers, CDNs, or customer-controlled gateways, assume inconsistent behavior and plan a supported fallback.

      Attribution:
    • EnnEmmEss #1
    • jefc1111 #1
    • entuno #1
    • ronbenton #1
  2. 02

    405 is better than silent corruption

    A new verb buys a cleaner failure mode. If QUERY is unsupported, intermediaries and servers should return 405 Method Not Allowed. Clients can detect that and retry with POST. When a GET body is stripped or ignored, the request may still succeed against the wrong inputs, which is much harder to catch and can produce subtle bad results.

    Prefer protocol changes that fail loudly over ones that preserve compatibility by guessing. For QUERY clients, build fallback logic around explicit 405 handling rather than hoping middleboxes preserve GET bodies.

      Attribution:
    • WorldMaker #1 #2
    • jy14898 #1
    • Ghoelian #1
  3. 03

    POST breaks semantics and tooling

    Using POST for reads works only if you ignore what the method tells the rest of the stack. Reverse proxies, browsers, and CDNs treat POST as potentially state-changing and usually skip normal cache behavior. That is why systems like Cloudflare end up using hacks such as synthesizing fake GET cache keys for POST-backed queries. QUERY gives those read requests a first-class shape instead of forcing every layer to special-case them.

    If you run search-heavy APIs behind edge caches or reverse proxies, method semantics are not cosmetic. Track where your stack relies on POST-for-read workarounds, because those are the places QUERY could eventually remove bespoke caching logic.

      Attribution:
    • locknitpicker #1 #2
    • rezonant #1
  4. 04

    QUERY replaces a two-step search resource pattern

    One existing workaround is to POST a search or filter resource and then GET it later. That makes the result shareable and cacheable, but it adds a second round trip and forces both client and server to manage temporary resources or persisted state. QUERY captures the same intent in one request and still allows the server to return a Location for a reusable GET URL when that is useful.

    If your API creates ad hoc search resources just to stay within HTTP semantics, QUERY may let you simplify that flow. Keep the GET URL pattern where sharing and repeat navigation matter, but stop forcing every query through resource creation.

      Attribution:
    • WorldMaker #1
    • theowaway213456 #1
    • lightningspirit #1
  5. 05

    Caching QUERY bodies is still messy

    Making QUERY cacheable in the spec does not make it operationally easy. A cache has to include the request body in the key, and formats like JSON can represent the same logical query in multiple byte forms through key order, whitespace, or number formatting. Bitwise body matching may work for some applications, but general-purpose caching across layers will stay spotty until clients and servers settle on stable serialized forms.

    Do not model the business case for QUERY around immediate CDN hit-rate gains. If you want caching, standardize your request serialization first and expect application-level control before shared infrastructure catches up.

      Attribution:
    • CodesInChaos #1
    • vshulcz #1
    • Yokohiii #1

Against the grain

  1. 01

    Standardizing GET bodies may have been simpler

    The anti-QUERY view is that the ecosystem upgrade cost is unavoidable, so spending it on a new verb just adds one more thing to teach and support. Old middleboxes that dislike GET bodies will also dislike an unknown method. On this view, expanding GET would have aligned the spec with how some systems already behave instead of creating parallel syntax for the same operation.

    If you own both ends of an API and most intermediaries, GET-with-body may remain the practical shortcut for a long time. Do not assume QUERY will erase legacy behavior quickly enough to simplify your stack in the near term.

      Attribution:
    • topham #1
    • akersten #1
    • nness #1
  2. 02

    QUERY could further weaken linkability

    Some saw QUERY as a quality-of-life feature for single-page apps that do not keep URL state aligned with application state. Because GET remains the method for directly addressable resources, QUERY may reinforce a split where interactive app state lives in opaque bodies instead of shareable links. That is defensible protocol design, but it can still push product teams toward less navigable web experiences.

    If you adopt QUERY for rich UI state, decide upfront which views must still round-trip to stable URLs. Otherwise teams may trade cleaner request semantics for worse sharing, refresh behavior, and debuggability.

      Attribution:
    • Yokohiii #1
    • lightningspirit #1
    • WorldMaker #1
  3. 03

    Maybe HTTP is the wrong layer

    A few comments rejected the entire exercise as over-optimizing a very old protocol. If your application mostly wants RPC over a durable connection, WebSockets or another custom transport may fit better than endlessly refining HTTP verbs. The pushback to that was blunt too: HTTP keeps winning because every proxy, cache, and piece of enterprise infrastructure already understands it.

    Before redesigning APIs around QUERY, check whether you actually need web-native semantics like caching, intermediaries, and addressability. If not, a different transport may remove more complexity than a new HTTP method can.

      Attribution:
    • austin-cheney #1
    • lightningspirit #1
    • lmariscal #1

In plain english

405 Method Not Allowed ↩
An HTTP response status meaning the server recognized the method name but does not allow it for the target resource.
API ↩
Application Programming Interface, a structured way for software systems to communicate with each other.
CloudFront ↩
Amazon Web Services' content delivery network and edge caching service.
Elasticsearch ↩
A search and analytics engine that exposes HTTP APIs for complex queries.
fetch ↩
The browser JavaScript API used to make network requests from web pages and web apps.
GET ↩
An HTTP method used to retrieve a resource, usually identified entirely by its URL.
GraphQL ↩
A query language and API style where clients request exactly the data they want, often sent today over HTTP POST.
HTTP ↩
Hypertext Transfer Protocol, the standard way web browsers, APIs, and servers send requests and responses over the web.
idempotent ↩
A property of an operation where making the same request multiple times has the same effect as making it once.
JSON ↩
JavaScript Object Notation, a common text format for structured data used in APIs.
OpenSearch ↩
An open source search and analytics engine derived from Elasticsearch.
POST ↩
An HTTP method commonly used to submit data or trigger server-side actions, often treated as potentially state-changing.
QUERY ↩
A newly standardized HTTP request method for safe, read-only requests that include a request body.
safe ↩
In HTTP, a request that is defined not to modify server state, such as a normal read operation.
WAF ↩
Web Application Firewall, a security layer that filters or blocks HTTP traffic based on rules.

Reference links

Standards and protocol references

  • WHATWG fetch issue 551
    Used to support the claim that browser fetch does not reliably support GET requests with a body.
  • RFC 10008 appendix A.3
    Referenced for the Accept-Query header that advertises QUERY support.
  • RFC 1945
    Cited as an older HTTP reference showing that GET semantics are tied to the Request-URI rather than a request body.

Prior discussions