HTTP has a new request method: QUERY.

For years, developers have mainly used GET to fetch data and POST to send or process data. But there has always been a grey area: complex read operations.

The Problem with GET

GET works perfectly when query parameters are simple.

GET /movies?genre=action&language=hindi

But real-world APIs often need complex filters, multiple values, ranges, sorting, and nested conditions.

For example:

{

  "genres": ["Action", "Thriller"],

  "languages": ["Hindi", "English"],

  "releaseYear": {

    "min": 2020

  }

}

Representing this cleanly in a URL can become difficult.

Why Developers Use POST for Search

A common solution is:

POST /movies/search

The filters are sent in the request body.

This works technically, but the intent is not always clear.

We are not creating a movie.

We are not updating server data.

We are simply querying information.

This is the gap the QUERY method is designed to address.

Introducing the QUERY Method

With QUERY, a client can send structured query content directly in the request.

QUERY /movies

Content-Type: application/json

{

  "genres": ["Action", "Thriller"],

  "languages": ["Hindi", "English"],

  "releaseYear": {

    "min": 2020

  }

}

The API intent is now much clearer: perform a query and return the result.

What Makes QUERY Different?

The QUERY method is defined as safe and idempotent.

Safe means the request should not change the server's state.

Idempotent means repeating the same request should have the same intended effect.

Because of these semantics, QUERY can also be handled differently from POST for capabilities such as retries and caching.

A simple mental model is:

GET → Fetch a resource

POST → Submit data for processing

QUERY → Execute a structured query

You can loosely think of QUERY as GET with a request body, although technically it has its own HTTP semantics.

Final Thoughts

The QUERY method may look like a small addition to HTTP, but it solves a common API design problem.

Instead of using POST /search for complex read operations, APIs now have a method that clearly communicates the actual intent of the request.

The ecosystem will still need time to mature around framework, proxy, gateway, and client support.

But for backend developers and system designers, QUERY is definitely a method worth understanding.

Reference: RFC 10008 — The HTTP QUERY Method