feat(v29): Supporting QUERY method (#3479)

# Supporting HTTP QUERY Method in express-zod-api

## Background: What Is HTTP QUERY?

The HTTP QUERY method is defined in **RFC 10008** (published June 2026,
Standards Track). In essence, QUERY is like GET but with a body. It is a
**safe and idempotent** request method that can carry request content —
a combination of properties that no existing standard HTTP method fully
satisfies.

QUERY requests that the target resource process the enclosed content
(the query) and respond with the result, without changing resource
state. The server uses the `Content-Type` to determine how to interpret
the body, and clients can discover QUERY support via the `Accept-Query`
response header.

**Key properties:**

| Property | QUERY | GET | POST |
|---|---|---|---|
| Safe | Yes | Yes | No |
| Idempotent | Yes | Yes | No |
| Can have body | Yes | No | Yes |
| Cacheable | Yes | Yes | With care |
| Request content in URI | Not required | Required | Not required |

## Why Use QUERY When GET and POST Already Exist?

### Problems with GET for queries

GET encodes the entire query in the URI. This has several drawbacks:

- **URI size limits** — many implementations (servers, proxies, CDNs)
cap URIs at ~8 KB, making complex queries impossible.
- **Encoding overhead** — binary data, complex filters, or structured
query languages must be URI-encoded, inflating size and reducing
readability.
- **Exposure** — URIs are more likely to be logged by intermediaries and
bookmarked by users, potentially leaking query details.

### Problems with POST for queries

POST is neither safe nor idempotent. Using it for queries means:

- **No safe retries** — intermediaries and clients cannot automatically
retry a POST on network failure, because the request might have mutated
state.
- **No caching** — POST responses are not cacheable by default, so
repeated identical queries cannot be served from a cache.
- **Semantic mismatch** — POST implies creation or mutation; using it
for read-only queries confuses tooling, monitoring, and human readers.

### How QUERY bridges the gap

QUERY is semantically a read operation (safe, idempotent, cacheable) but
with body support like POST. This makes it the natural choice for:

- Complex search/filter APIs (GraphQL, Elasticsearch, SQL-over-HTTP)
- APIs with large or structured query payloads
- Any read operation where the query exceeds URI size limits
- Safe operations that need content negotiation via `Content-Type`

## What Would It Take to Add QUERY Support?

### Current state

- **Node.js** (22.19+, 24.x, 26.x) already has `QUERY` in `http.METHODS`
— the parser accepts it.
- **Express 5.1.x** at runtime handles QUERY correctly via its
Layer-based routing — Express does not restrict which methods can be
routed.
- **Express types** (`@types/express-serve-static-core`) do not list
`query` on `IRouter`. This is a deliberate policy: Express adds type
entries only when the IETF method reaches sufficient maturity. (For
reference, Express also does not type `"query"` despite it being the
`?key=val` part of a URL — the name collision is coincidental.)


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added support for the HTTP **QUERY** method (RFC 10008), including
typed client/endpoints and default input handling (query, body, and path
params).
* Documentation improvements for OpenAPI **3.2.0** (including SSE schema
handling) and enhanced security depiction (OAuth2 device authorization).
* **Bug Fixes**
* Improved routing initialization to validate **QUERY** registration and
raise clearer errors when unsupported.
* **Documentation**
* Updated generated docs/snapshots and example payload structure
(`value` → `dataValue`), and adjusted documentation constructor inputs
to `info` + `server`.
* **Tests**
* Expanded coverage for **QUERY** routing, extraction, typing, and
documentation output.
* **Chores**
* Updated server startup lifecycle to treat hooks as synchronous, and
removed the deprecated `Integration.create()` factory.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: RobinTail

CHANGELOG.md

@@ -8,10 +8,14 @@
 - The static async method `Integration::create()` removed — use `new Integration()` instead;
 - Server lifecycle hooks (`beforeRouting` and `afterRouting` config options) are no longer async;
 - The `createServer()` function is now synchronous — that should simplify the daily routines for beginners;
-- The Documentation generator is featuring the OpenAPI 3.2.0 with better SSE support and other features;
 - Changes to `Documentation` constructor:
   - `serverUrl` renamed to `server` and now also accepts OpenAPI's ServerObject;
   - `title` and `version` must be wrapped into `info`, assignable with OpenAPI's InfoObject;
+- The Documentation generator is featuring the OpenAPI 3.2.0 with better SSE support and other features;
+- Added HTTP QUERY method support (RFC 10008):
+  - The QUERY method is like GET but with a body — safe, idempotent, and cacheable;
+  - Default input sources for QUERY: `["query", "body", "params"]` (from the lowest priority to highest);
+  - Supported by `Integration` and `Documentation` generators.
 
 ```diff
 - await Integration.create({});

dataflow.svg

@@ -20,6 +20,7 @@ const users = [
  * */
 export const listUsersEndpoint = arrayRespondingFactory.build({
   tag: "users",
+  method: "query",
   input: z.object({
     roles: z.array(roleSchema).optional(),
   }),

example/endpoints/list-users.ts

@@ -160,49 +160,28 @@ interface PostV1UserCreateNegativeResponseVariants {
   500: PostV1UserCreateNegativeVariant2;
 }
 
-/** get /v1/user/list */
-type GetV1UserListInput = {
+/** query /v1/user/list */
+type QueryV1UserListInput = {
   roles?: ("manager" | "operator" | "admin")[] | undefined;
 };
 
-/** get /v1/user/list */
-type GetV1UserListPositiveVariant1 = {
+/** query /v1/user/list */
+type QueryV1UserListPositiveVariant1 = {
   name: string;
   role: "manager" | "operator" | "admin";
 }[];
 
-/** get /v1/user/list */
-interface GetV1UserListPositiveResponseVariants {
-  200: GetV1UserListPositiveVariant1;
+/** query /v1/user/list */
+interface QueryV1UserListPositiveResponseVariants {
+  200: QueryV1UserListPositiveVariant1;
 }
 
-/** get /v1/user/list */
-type GetV1UserListNegativeVariant1 = string;
+/** query /v1/user/list */
+type QueryV1UserListNegativeVariant1 = string;
 
-/** get /v1/user/list */
-interface GetV1UserListNegativeResponseVariants {
-  400: GetV1UserListNegativeVariant1;
-}
-
-/** head /v1/user/list */
-type HeadV1UserListInput = {
-  roles?: ("manager" | "operator" | "admin")[] | undefined;
-};
-
-/** head /v1/user/list */
-type HeadV1UserListPositiveVariant1 = undefined;
-
-/** head /v1/user/list */
-interface HeadV1UserListPositiveResponseVariants {
-  200: HeadV1UserListPositiveVariant1;
-}
-
-/** head /v1/user/list */
-type HeadV1UserListNegativeVariant1 = undefined;
-
-/** head /v1/user/list */
-interface HeadV1UserListNegativeResponseVariants {
-  400: HeadV1UserListNegativeVariant1;
+/** query /v1/user/list */
+interface QueryV1UserListNegativeResponseVariants {
+  400: QueryV1UserListNegativeVariant1;
 }
 
 /** post /v1/login */
@@ -557,16 +536,22 @@ export type Path =
   | "/v1/forms/feedback"
   | "/v2/users/list";
 
-export type Method = "get" | "post" | "put" | "delete" | "patch" | "head";
+export type Method =
+  | "get"
+  | "post"
+  | "put"
+  | "delete"
+  | "patch"
+  | "query"
+  | "head";
 
 export interface Input {
   "get /v1/user/retrieve": GetV1UserRetrieveInput;
   "head /v1/user/retrieve": HeadV1UserRetrieveInput;
   "delete /v1/user/:id/remove": DeleteV1UserIdRemoveInput;
   "patch /v1/user/:id": PatchV1UserIdInput;
   "post /v1/user/create": PostV1UserCreateInput;
-  "get /v1/user/list": GetV1UserListInput;
-  "head /v1/user/list": HeadV1UserListInput;
+  "query /v1/user/list": QueryV1UserListInput;
   "post /v1/login": PostV1LoginInput;
   /** @deprecated */
   "get /v1/avatar/send": GetV1AvatarSendInput;
@@ -589,8 +574,7 @@ export interface PositiveResponse {
   "delete /v1/user/:id/remove": SomeOf<DeleteV1UserIdRemovePositiveResponseVariants>;
   "patch /v1/user/:id": SomeOf<PatchV1UserIdPositiveResponseVariants>;
   "post /v1/user/create": SomeOf<PostV1UserCreatePositiveResponseVariants>;
-  "get /v1/user/list": SomeOf<GetV1UserListPositiveResponseVariants>;
-  "head /v1/user/list": SomeOf<HeadV1UserListPositiveResponseVariants>;
+  "query /v1/user/list": SomeOf<QueryV1UserListPositiveResponseVariants>;
   "post /v1/login": SomeOf<PostV1LoginPositiveResponseVariants>;
   /** @deprecated */
   "get /v1/avatar/send": SomeOf<GetV1AvatarSendPositiveResponseVariants>;
@@ -613,8 +597,7 @@ export interface NegativeResponse {
   "delete /v1/user/:id/remove": SomeOf<DeleteV1UserIdRemoveNegativeResponseVariants>;
   "patch /v1/user/:id": SomeOf<PatchV1UserIdNegativeResponseVariants>;
   "post /v1/user/create": SomeOf<PostV1UserCreateNegativeResponseVariants>;
-  "get /v1/user/list": SomeOf<GetV1UserListNegativeResponseVariants>;
-  "head /v1/user/list": SomeOf<HeadV1UserListNegativeResponseVariants>;
+  "query /v1/user/list": SomeOf<QueryV1UserListNegativeResponseVariants>;
   "post /v1/login": SomeOf<PostV1LoginNegativeResponseVariants>;
   /** @deprecated */
   "get /v1/avatar/send": SomeOf<GetV1AvatarSendNegativeResponseVariants>;
@@ -642,10 +625,8 @@ export interface EncodedResponse {
     PatchV1UserIdNegativeResponseVariants;
   "post /v1/user/create": PostV1UserCreatePositiveResponseVariants &
     PostV1UserCreateNegativeResponseVariants;
-  "get /v1/user/list": GetV1UserListPositiveResponseVariants &
-    GetV1UserListNegativeResponseVariants;
-  "head /v1/user/list": HeadV1UserListPositiveResponseVariants &
-    HeadV1UserListNegativeResponseVariants;
+  "query /v1/user/list": QueryV1UserListPositiveResponseVariants &
+    QueryV1UserListNegativeResponseVariants;
   "post /v1/login": PostV1LoginPositiveResponseVariants &
     PostV1LoginNegativeResponseVariants;
   /** @deprecated */
@@ -690,12 +671,9 @@ export interface Response {
   "post /v1/user/create":
     | PositiveResponse["post /v1/user/create"]
     | NegativeResponse["post /v1/user/create"];
-  "get /v1/user/list":
-    | PositiveResponse["get /v1/user/list"]
-    | NegativeResponse["get /v1/user/list"];
-  "head /v1/user/list":
-    | PositiveResponse["head /v1/user/list"]
-    | NegativeResponse["head /v1/user/list"];
+  "query /v1/user/list":
+    | PositiveResponse["query /v1/user/list"]
+    | NegativeResponse["query /v1/user/list"];
   "post /v1/login":
     | PositiveResponse["post /v1/login"]
     | NegativeResponse["post /v1/login"];
@@ -744,8 +722,7 @@ export const endpointTags = {
   "delete /v1/user/:id/remove": ["users"],
   "patch /v1/user/:id": ["users"],
   "post /v1/user/create": ["users"],
-  "get /v1/user/list": ["users"],
-  "head /v1/user/list": ["users"],
+  "query /v1/user/list": ["users"],
   "post /v1/login": ["cookies"],
   "get /v1/avatar/send": ["files", "users"],
   "head /v1/avatar/send": ["files", "users"],

example/example.client.ts

@@ -388,26 +388,28 @@ paths:
                   - reason
                 additionalProperties: false
   /v1/user/list:
-    get:
-      operationId: GetV1UserList
+    query:
+      operationId: QueryV1UserList
       tags:
         - users
-      parameters:
-        - name: roles
-          in: query
-          required: false
-          description: GET /v1/user/list Parameter
-          schema:
-            type: array
-            items:
-              type: string
-              enum:
-                - manager
-                - operator
-                - admin
+      requestBody:
+        description: QUERY /v1/user/list Request body
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                roles:
+                  type: array
+                  items:
+                    type: string
+                    enum:
+                      - manager
+                      - operator
+                      - admin
       responses:
         "200":
-          description: GET /v1/user/list Positive response
+          description: QUERY /v1/user/list Positive response
           content:
             application/json:
               schema:
@@ -437,36 +439,14 @@ paths:
                     - name: Patti Harrison
                       role: admin
         "400":
-          description: GET /v1/user/list Negative response
+          description: QUERY /v1/user/list Negative response
           content:
             text/plain:
               schema:
                 type: string
               examples:
                 example1:
                   dataValue: Sample error message
-    head:
-      operationId: HeadV1UserList
-      tags:
-        - users
-      parameters:
-        - name: roles
-          in: query
-          required: false
-          description: HEAD /v1/user/list Parameter
-          schema:
-            type: array
-            items:
-              type: string
-              enum:
-                - manager
-                - operator
-                - admin
-      responses:
-        "200":
-          description: HEAD /v1/user/list Positive response
-        "400":
-          description: HEAD /v1/user/list Negative response
   /v1/login:
     post:
       operationId: PostV1Login

example/example.documentation.yaml

@@ -117,6 +117,7 @@ describe("Example", async () => {
       signal,
     }) => {
       const response = await fetch(`http://localhost:${port}/v1/user/list`, {
+        method: "QUERY",
         signal,
       });
       expect(response.status).toBe(200);

example/index.spec.ts

@@ -48,6 +48,7 @@ export const defaultInputSources: InputSources = {
   put: ["body", "params"],
   patch: ["body", "params"],
   delete: ["query", "params"],
+  query: ["query", "body", "params"],
 };
 const fallbackInputSources: InputSource[] = ["body", "query", "params"];
 

express-zod-api/src/common-helpers.ts

@@ -284,7 +284,7 @@ export const depictRequestParams = ({
       (isHeader?.(name, method, path) ?? defaultIsHeader(name, securityHeaders))
     )
       return "header";
-    if (isQueryEnabled) return "query";
+    if (isQueryEnabled && method !== "query") return "query";
   };
 
   return Object.entries(flat.properties).reduce<ParameterObject[]>(

express-zod-api/src/documentation-helpers.ts

@@ -2,17 +2,18 @@ import type { IRouter } from "express";
 
 export type SomeMethod = Lowercase<string>;
 
-type FamiliarMethod = Exclude<
-  keyof IRouter,
-  "param" | "use" | "route" | "stack"
->;
+type FamiliarMethod =
+  | Exclude<keyof IRouter, "param" | "use" | "route" | "stack" | "all">
+  /** @todo remove when Express team added the "query" method into their types officially */
+  | "query";
 
 export const methods = [
   "get",
   "post",
   "put",
   "delete",
   "patch",
+  "query",
 ] satisfies Array<FamiliarMethod>;
 
 export const clientMethods = [
@@ -23,7 +24,7 @@ export const clientMethods = [
 /**
  * @desc Methods supported by the framework API to produce Endpoints on EndpointsFactory.
  * @see BuildProps
- * @example "get" | "post" | "put" | "delete" | "patch"
+ * @example "get" | "post" | "put" | "delete" | "patch" | "query"
  * */
 export type Method = (typeof methods)[number];
 

express-zod-api/src/method.ts

@@ -1,4 +1,4 @@
-import type { IRouter, RequestHandler } from "express";
+import type { IRouter, RequestHandler, IRouterMatcher } from "express";
 import createHttpError from "http-errors";
 import { isProduction } from "./common-helpers";
 import type { CommonConfig } from "./config-type";
@@ -106,7 +106,10 @@ export const initRouting = ({ app, config, getLogger, ...rest }: InitProps) => {
         const logger = getLogger(request);
         return endpoint.execute({ request, response, logger, config });
       });
-      app[method](path, ...handlers);
+      /** @todo remove type assertion when Express teams adds the QUERY method into types officially */
+      const register: (path: string, ...handlers: RequestHandler[]) => IRouter =
+        (app as IRouter & { query: IRouterMatcher<IRouter> })[method];
+      register.call(app, path, ...handlers);
     }
     if (config.hintAllowedMethods === false) continue;
     deprioritized.set(path, createWrongMethodHandler(accessMethods));