QUERY: The Missing HTTP Method for REST API

Filtering data in REST APIs sounds simple until your GET URL becomes too long.

The new HTTP QUERY method tries to fix that gap: it lets you send complex search/filter data in the request body, without abusing POST.

The Problem: GET Gets Messy Fast #

For simple reads, GET works great. Even simple filters are fine.

But real APIs often need more:

• many filters
• nested conditions
• pagination
• sorting
• date ranges
• user-specific search rules

Soon your URL becomes hard to read, hard to encode, and sometimes too long.

Thiago explained the pain clearly:

Most of us try to use the GET method. It’s probably the best way to do that. However, this can be an issue depending on how many parameters we have.

That’s when many teams switch to POST.

Why POST Was A Workaround #

Developers often use POST for complex search because it supports a body. This is practical, but it’s not ideal.

POST usually means “create or change something.” Search and filtering should not change server state. That mismatch can confuse developers, API clients, proxies, caches, and documentation tools.

Yugo gave a simple rule of thumb:

If you were going to implement a POST to get information, use QUERY instead.

What QUERY Changes #

The QUERY method is designed for complex reads with a request body.

Example:

QUERY /users
Content-Type: application/json

{
  "status": "active",
  "roles": ["admin", "editor"],
  "sort": {
    "field": "createdAt",
    "direction": "desc"
  },
  "page": {
    "number": 2,
    "size": 50
  }
}

In simple words:

• Use GET for simple reads.
• Use QUERY for complex reads.
• Use POST when you create or trigger a change.

Thiago summarized the difference:

POST is not created for filtering. Now we have QUERY, which is idempotent and cacheable, so it’s much better for this use case.

Two important words here:

• Idempotent: sending the same request many times should not change the server state.
• Cacheable: responses may be easier for HTTP tools to cache, depending on headers and implementation.

When Should You Use QUERY? #

Don’t replace every GET tomorrow. Use it where it gives clear value.

Good cases for QUERY:

• advanced search screens
• reporting APIs
• analytics filters
• data-heavy internal tools
• filters with nested JSON
• requests that may exceed URL length limits

Keep using GET for:

GET /users/123
GET /users?status=active
GET /orders/2026-001

Use QUERY when the filter becomes a real object, not just a few parameters.

Create Team Guidelines Early #

One risk is inconsistency. One service uses GET, another uses POST, another uses QUERY, and now everyone is confused.

Thiago recommended having clear API rules:

If you’re working with many APIs or microservices, the best thing is to have a guideline, so all APIs follow the same guideline.

A simple team guideline could be:

1. Use GET for simple reads by ID or simple query parameters.
2. Use QUERY when the request needs a complex body.
3. Don’t use POST only because GET feels too small.
4. Document examples in your OpenAPI spec.
5. Version your API if changing an existing POST /search endpoint to QUERY.

Practical Advice For Developers #

If you’re designing a new REST API, ask these questions:

• Does this endpoint only read data?
• Do I need a request body for filters?
• Would using POST feel wrong because nothing is created?
• Could the URL become too long or hard to maintain?

If the answer is yes, QUERY may be the right fit.

For existing APIs, don’t rush. Check if your framework, API gateway, client libraries, and documentation tools support QUERY. Support is still being added in many ecosystems.

Final Takeaway #

QUERY fills a long-standing gap in REST API design. It gives us a cleaner way to handle complex filtering without forcing everything into GET URLs or misusing POST.

Use GET for simple reads, QUERY for complex reads, and POST for changes. Your APIs will be clearer, easier to document, and easier for other developers to understand.

YouTube link to the original OotBD session