The HTTP Query Method

Original Article ↗ Hacker News Discussion ↗

Role and Semantics of QUERY

  • QUERY is discussed as “GET with a body”: safe and idempotent like GET, but allowing complex parameters in the request body.
  • Several participants stress the distinction between safe (read-only from the client’s perspective) and merely idempotent (like PUT).
  • Supporters say the point is to restore clear semantics: POST is semantically “unsafe / non-idempotent”; QUERY would be a standard, machine-readable way to say “this is a read-only, cacheable query with a body.”
  • Critics argue semantics already aren’t enforced (servers routinely mutate on GET, use POST for queries), so adding another verb just multiplies syntax without solving real discipline problems.

Why Not Just Use GET (or POST) with a Body?

  • Some say simply allowing GET bodies would solve the problem; others reply that decades of middleware assume GET has no body, and many proxies/CDNs strip or ignore it.
  • RFC 9110 is cited: GET bodies have “no generally defined semantics,” can be rejected, and can enable request-smuggling attacks.
  • Using POST for queries is common today but loses automatic assumptions about safety, retries, caching, and can confuse new developers (“why is a read-only query POST?”).

Caching, Intermediaries, and Safety

  • A major pro-QUERY argument: intermediaries (CDNs, proxies, API gateways, browsers) can safely enable caching and retries when they see a standardized safe method.
  • Opponents counter that you could instead document “idempotent POST” or configure caches per-endpoint; adding a verb is seen as overkill or redundant.

Practical Motivations

  • Real-world pain points:
    • URLs exceeding length limits (e.g., CloudFront) due to large filter sets or complex queries.
    • Need to keep sensitive parameters out of query strings/logs.
    • APIs/GraphQL/Elasticsearch-like queries that don’t fit nicely into URLs.
  • Some like QUERY as aligning with CQRS/DDD’s “query vs command” separation.

Adoption, UX, and Alternatives

  • Concern that misuse could hurt bookmarkability and shareable URLs; others say user-facing, bookmarkable views should stay GET anyway.
  • Skeptics predict extremely slow adoption and limited real-world use; some call it “waste of time.”
  • Others note non-standard methods already work poorly through CORS, proxies, and tooling, so standardization is valuable.
  • Alternatives mentioned: POST-everything APIs, JSON-RPC over HTTP, creating “saved search” resources (POST to create, GET by ID) instead of huge one-shot queries.