HTTP has long relied on a small set of core methods like GET, POST, PUT, PATCH, and DELETE. A new proposal worth understanding is the HTTP QUERY method, which is designed for expressive, cache-friendly requests that ask for a resource representation without causing side effects.

What is the QUERY method?

The QUERY method is intended to be a safe, idempotent way to express a data retrieval request that may be more semantically explicit than GET when the request is primarily about filtering, searching, or querying a resource set.

While GET already handles request queries via URL parameters, QUERY can clearly communicate intent:

• The request is about searching or querying data
• The request should not change server state
• The request may be safely cached and replayed

Why would you use QUERY instead of GET?

GET can become overloaded when APIs need to distinguish between simple retrieval and a request that executes a complex search pipeline.

QUERY can be useful when:

• you want to separate a query semantics layer from regular URI retrieval
• your API supports declarative query expressions or search DSLs
• you want a clear signal to caches and middleware that this request is safe

Example usage

A client could issue a QUERY request against a collection endpoint, with filtering instructions in the request body or query string:

QUERY /api/products HTTP/1.1
Content-Type: application/json

{
  "filter": {
    "category": "backend",
    "status": "stable"
  },
  "sort": "publishedAt desc",
  "limit": 12
}

The server would respond with a JSON payload containing the matching products, but nothing in the request should imply a state change.

Semantic advantages

Using QUERY can improve the clarity of your API contract in several ways:

• Intent-first API design: clients explicitly request query semantics rather than reusing GET for everything.
• Cache friendliness: the request is conceptually safe and can be cached or replayed in proxies.
• Separation of concerns: query evaluation and resource retrieval are distinct concerns.

What it does not replace

This method is not meant to replace GET for standard page or document retrieval. It is also not a substitute for POST in cases where the request intentionally changes server data or triggers a workflow.

Use QUERY when the request is:

• read-only
• search-oriented
• declarative in nature

For state-changing operations, keep using POST, PUT, PATCH, or DELETE.

Compatibility and ecosystem

A major hurdle for any new HTTP method is support across clients, servers, and middleware. Many HTTP libraries and proxies are built around the standard methods, so adding QUERY requires:

• framework support for custom methods
• CORS configuration if browsers are involved
• cache rules or headers that treat it as safe

In practice, many teams may map QUERY to POST internally while keeping the semantics distinct at the API layer.

Practical API design patterns

If you decide to adopt QUERY, keep these rules in mind:

• keep query request bodies small and declarative
• avoid using QUERY for actions with side effects
• preserve caching behavior with Cache-Control or ETag
• document query parameters and accepted request bodies clearly

A helpful pattern is to expose endpoints like /api/query/products and /api/query/orders when the endpoint is optimized for search-style payloads.

When to prefer GET instead

For simple, resource-oriented requests with standard query parameters like ?page=2&limit=20, GET is still the best choice.

QUERY makes the most sense when you need:

• a richer, JSON-driven search payload
• a clear semantic boundary for query evaluation
• explicit safe-read semantics in a custom API

Final thoughts

The QUERY HTTP method is an interesting idea for APIs that want to make query intent explicit. It is not yet ubiquitous, but it can be a useful design pattern when combined with strong API documentation and careful cache handling.

For most projects, the simplest approach remains standard GET for retrieval and POST or PATCH for changes. But if your product needs a dedicated query-first surface, QUERY is worth exploring.