The New QUERY Method in OpenAPI 3.2: A Small Addition That Clears Up a Big Ambiguity

<p>One of the quieter updates in OpenAPI 3.2 is support for a new HTTP method: QUERY.</p><p>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.</p><h3 id="why-query-exists">Why QUERY Exists</h3><p>Traditionally, REST APIs have used GET for anything that retrieves data. But GET comes with a few assumptions baked in by the HTTP spec:</p><ul><li>Requests must be idempotent (no side effects).</li><li>Requests can’t have a body.</li><li>Parameters have to fit into the URL query string.</li></ul><p>That last point has caused trouble.</p><p>Some APIs need to send complex filters, nested objects, or large request payloads — all while keeping the operation read-only.</p><p>GET doesn’t allow that.</p><p>POST does, but using POST for read-only queries violates the spirit of HTTP semantics and breaks cacheability.</p><p>The new QUERY method is meant to fix that gap.</p><h3 id="what-query-does">What QUERY Does</h3><p>QUERY is a read-only method that allows a request body.</p><p>That means you can write operations like:</p><pre>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'</pre><p>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.</p><h3 id="why-it-matters">Why It Matters</h3><p>For API consumers, this makes specs and SDKs more predictable.</p><p>For API authors, it allows expressive query operations without semantic compromises.</p><p>Here’s what changes in practice:</p><ul><li>Cleaner API design: You no longer need to overload POST just because your query has a JSON payload.</li><li>Better caching: Since QUERY is explicitly read-only, it’s easier to implement caching semantics safely.</li><li>Improved documentation: Docs and SDKs can clearly label query endpoints as non-mutating, even with request bodies.</li></ul><h3 id="tooling-and-adoption">Tooling and Adoption</h3><p>This is where things get interesting.</p><p>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.</p><p>That means you can document QUERY operations today, but whether they’ll run as-is depends on your stack:</p><ul><li>Many frameworks will reject unknown methods until they’re explicitly supported.</li><li>API gateways and reverse proxies (like NGINX or Cloudflare) might block them unless configured to pass them through.</li><li>SDK generators and clients will need to update their request builders to handle QUERY gracefully.</li></ul><p>So in practice, QUERY is more of a forward-looking signal than a production-ready feature right now.</p><p>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.</p><h3 id="a-step-toward-clarity">A Step Toward Clarity</h3><p>The addition of QUERY isn’t about introducing something new — it’s about naming what developers have already been doing.</p><p>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.</p><p>It’s another small example of how OpenAPI evolves thoughtfully: by turning common patterns into first-class citizens.</p>