🎉 Now supported in DeveloperHub

One of the quieter updates in OpenAPI 3.2 is support for a new HTTP method: QUERY.

It’s small, but it clarifies something that’s been fuzzy in API design for years — how to represent read-only, query-style operations that aren’t strictly GET.

Why QUERY Exists

Traditionally, REST APIs have used GET for anything that retrieves data. But GET comes with a few assumptions baked in by the HTTP spec:

  • Requests must be idempotent (no side effects).
  • Requests can’t have a body.
  • Parameters have to fit into the URL query string.

That last point has caused trouble.

Some APIs need to send complex filters, nested objects, or large request payloads — all while keeping the operation read-only.

GET doesn’t allow that.

POST does, but using POST for read-only queries violates the spirit of HTTP semantics and breaks cacheability.

The new QUERY method is meant to fix that gap.

What QUERY Does

QUERY is a read-only method that allows a request body.

That means you can write operations like:

paths:
  /search:
    query:
      summary: Search for users
      description: Performs a read-only query with a complex filter
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                filters:
                  type: object
                  properties:
                    country:
                      type: string
                    active:
                      type: boolean
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'

This example describes a search endpoint that can take a JSON body instead of a long, hard-to-parse URL query string — while remaining strictly read-only.

Why It Matters

For API consumers, this makes specs and SDKs more predictable.

For API authors, it allows expressive query operations without semantic compromises.

Here’s what changes in practice:

  • Cleaner API design: You no longer need to overload POST just because your query has a JSON payload.
  • Better caching: Since QUERY is explicitly read-only, it’s easier to implement caching semantics safely.
  • Improved documentation: Docs and SDKs can clearly label query endpoints as non-mutating, even with request bodies.

Tooling and Adoption

This is where things get interesting.

While OpenAPI 3.2 now recognises QUERY, many web servers, frameworks, and HTTP libraries don’t — at least not yet. The method is new to the specification world, but not yet part of the core HTTP vocabulary most runtimes expect.

That means you can document QUERY operations today, but whether they’ll run as-is depends on your stack:

  • Many frameworks will reject unknown methods until they’re explicitly supported.
  • API gateways and reverse proxies (like NGINX or Cloudflare) might block them unless configured to pass them through.
  • SDK generators and clients will need to update their request builders to handle QUERY gracefully.

So in practice, QUERY is more of a forward-looking signal than a production-ready feature right now.

Teams can start by using it in their OpenAPI specs to clarify intent — even if they continue serving those endpoints via POST temporarily. Over time, as web servers and tooling catch up, these definitions will become executable, not just descriptive.

A Step Toward Clarity

The addition of QUERY isn’t about introducing something new — it’s about naming what developers have already been doing.

Many APIs have had “read-only POST” endpoints for years. Now, with OpenAPI 3.2, there’s a consistent, standards-based way to describe them.

It’s another small example of how OpenAPI evolves thoughtfully: by turning common patterns into first-class citizens.