Meet HTTP QUERY: The Safe, Cacheable Method We've Been Waiting For

With the official standardization of RFC 10008 in June 2026, the HTTP protocol has introduced a brand new request method: QUERY.

For years, developers have had to make awkward architectural trade-offs when requesting complex or large search operations from a server. The QUERY method solves this fundamental limitation.

In this post, we'll dive deep into exactly what QUERY is, why it was created, and how it will change modern web API design.

The Old Dilemma: GET vs. POST

Historically, web developers had only two primary choices when querying resources from an API: GET and POST. Both come with severe trade-offs when building complex data-retrieval features.

1. The GET Method

GET is meant to retrieve data. It is defined by HTTP standards as safe and idempotent. This allows browsers, proxies, and CDNs to cache responses seamlessly.

However, GET does not support a standard request body. To filter, sort, or paginate, developers must encode parameters into the URL query string: GET /api/users?role=admin&status=active&sort=name&page=1.

• URL Limits: Browsers and servers enforce maximum URL length limits (often ~2KB). Complex queries easily exceed this.
• Security Leaks: Query strings are written into browser history, server access logs, and proxy logs. Putting sensitive search values here is a significant risk.
• Poor Readability: Nested logic is incredibly messy to encode into query parameters.

2. The POST Method

To bypass URL limitations, many APIs (most notably GraphQL and Elasticsearch) use POST for search queries. This allows them to pass arbitrary JSON payloads in the request body.

• Incorrect Semantics: POST is meant for state-altering actions (e.g. creating records).
• Non-Cacheable: Intermediaries cannot safely cache POST responses.
• Resubmission Prompts: Reloading a browser page loaded via a POST request prompts a form resubmission warning.

Enter HTTP QUERY (RFC 10008)

The QUERY method bridges this gap. It is explicitly designed for cases where a client needs to fetch data using a complex query structure that doesn't fit in a URL, without modifying any state.

Feature	GET	POST	QUERY
Request Body	❌ No	✔️ Yes	✔️ Yes
Safe (No side-effects)	✔️ Yes	❌ No	✔️ Yes
Idempotent (Safe to retry)	✔️ Yes	❌ No	✔️ Yes
Standard Caching	✔️ Yes	❌ No	✔️ Yes (URL + Body)

How Caching Works with QUERY

Since QUERY requests contain a payload that determines the response, standard HTTP caching must adapt. When caching a QUERY response, the cache key can no longer just be the request URL. Instead, caching intermediaries must calculate a cache key that incorporates the request body.

This unlocks native CDN caching for heavy, complex query-based endpoints, which was previously impossible without custom hacks for POST requests.

Practical Examples

1. JSON Search Request

Instead of encoding complex filters into a URL, we can send a clean, readable JSON payload:

QUERY /documents HTTP/1.1
Host: api.example.com
Content-Type: application/json
Accept: application/json

{
  "search": "artificial intelligence",
  "published_year": {
    "from": 2024,
    "to": 2026
  },
  "tags": ["tech", "ai", "web"],
  "sort_by": "relevance"
}

2. GraphQL over HTTP QUERY

GraphQL heavily relies on POST to fetch queries. With the QUERY method, GraphQL queries can now be semantically aligned and cached cleanly:

QUERY /graphql HTTP/1.1
Host: api.example.com
Content-Type: application/graphql
Accept: application/json

query {
  user(id: "12345") {
    name
    email
    orders(first: 5) {
      id
      total
    }
  }
}

Advertising Support: The Accept-Query Header

To prevent clients from sending payload formats the server doesn't understand, RFC 10008 introduces the Accept-Query response header. When a server responds to an options request or an error, it can advertise which media types it accepts for QUERY:

HTTP/1.1 200 OK
Allow: GET, POST, QUERY, OPTIONS
Accept-Query: application/json, application/graphql, application/sql

This tells the client that they can safely use the QUERY method on this endpoint using JSON, GraphQL, or SQL formats.

Summary and Key Takeaways

The addition of QUERY represents a major evolution in how we build APIs:

• No more "GET vs. POST" hacks: You no longer have to choose between clean HTTP caching semantics and arbitrary payload sizes.
• Better Security: Sensitive filter parameters can be kept inside the request body rather than leaking into server logs or browser history via URLs.
• Optimized Performance: CDNs and proxies can now natively cache search results based on the query body, significantly reducing server loads for read-heavy query APIs.

As web servers, CDNs, and client frameworks start rolling out native support for RFC 10008, QUERY is set to become the standard way we interact with search and analytical endpoints.