Beyond GET and POST: The New HTTP Method "QUERY" Explained

Building or consuming web APIs has always forced a frustrating choice: How do you send heavy, complex data filters to a server without breaking standard HTTP rules?

For years, developers have been stuck choosing between the URL limitations of GET and the semantic violations of POST. That compromise ends now. The IETF has officially published RFC 10008, standardizing the brand-new HTTP QUERY method. It is the first major HTTP verb added to our toolkit since `PATCH` arrived in 2010.

Here is exactly why the QUERY method changes the game for API design and how it works.

The Problem: The "GET vs POST" Search API Trap

When designing search endpoints, traditional HTTP methods present severe limitations:

• The Problem with GET: GET parameters live in the URL string. Complex, nested JSON objects quickly hit browser and proxy URL length limits (typically ~8,000 characters). Furthermore, sensitive data passed via URLs gets leaked in server access logs and browser histories.
• The Problem with POST: To bypass URL limits, developers use `POST` to carry a request body. However, `POST` is designed for state-changing operations. It is neither safe nor idempotent, meaning CDNs refuse to cache it. Furthermore, dropped connections cannot be safely retried automatically by clients.

Note on GET with a body: While technically possible, the HTTP specification dictates that a GET request body has no defined semantics. Firewalls and API gateways frequently strip or ignore them entirely.

What is the HTTP QUERY Method?

The QUERY method acts as a hybrid. It delivers the large request body of a POST combined with the safe, idempotent, and cacheable semantics of a GET.

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

{
 "category": "electronics",
 "price": { "gte": 500, "lte": 1500 },
 "tags": ["4k", "oled"]
}

Core Technical Rules:

1. Mandatory Content-Type: Unlike GET, a QUERY request must provide a Content-Type header (e.g., `application/json` or `application/sql`) so the server knows how to parse the payload.

2. Body-Based Caching: CDNs and proxies can cache QUERY responses by hashing the request body alongside the metadata to form the cache key.

Important Question? Where Do We Need It? (Ideal Use Cases)

Implement QUERY for data-heavy operations that require reading without mutation:

E-Commerce Filtering Engines: Complex matrices of size, pricing, location, and ratings.

Analytics and Reporting Dashboards: Passing time-series formulas, custom metric aggregations, or heavy filtering blocks.

GraphQL & Database Gateways: Fetching data via large GraphQL query strings or service-to-service JSONPath queries.

Is it a Complete Replacement for GET?

Absolutely Not. GET remains the definitive choice for fetching explicit, direct resources (e.g., `GET /users/123`). QUERY is designed to eliminate the bad practice of using `POST` for complex search filters.

Are you ready to drop your `POST` search endpoints for `QUERY`?