Home
← writing

Understanding the HTTP QUERY Method

A new HTTP method for safe, cacheable requests with bodies — and why it matters for API design.

Jun 18, 2026· 6 min· #http #api #protocols

The HTTP QUERY method fills an awkward gap. For years, engineers have overloaded POST to send search parameters that were too large or too complex for a URL. That works, but it breaks caches and confuses intermediaries.

What QUERY does

QUERY is safe, idempotent, and cacheable, but unlike GET it accepts a request body. That means:

  • Long search filters can live in the body, not the URL
  • Intermediaries can cache responses by hashing the body
  • Semantics stay clean: you are asking, not changing

When to reach for it

Prefer GET when the request fits comfortably in a URL. Reach for QUERY when it doesn't.

Good candidates:

  1. Full-text search with dozens of filters
  2. GraphQL-style read queries
  3. Batch lookups by id list

What to watch for

Support is still landing across clients and proxies. Feature-detect and fall back to POST with a X-HTTP-Method-Override: QUERY header until adoption catches up.