microsoft / microsoft/typespec

[Feature Request] HTTP: support the QUERY method (RFC 10008) and OpenAPI 3.2 `query` operation emission

Open
#11,171 3 comments 1 reaction 0 assignees View on GitHub
design:needed feature lib:http triaged:core
Dominant language
Java
Stars
5.9k
Forks
394
Avg merge
1d 23h
Merged PRs (30d)
104

Description

## Clear and concise description of the problem

The HTTP `QUERY` method is now a Proposed Standard — [RFC 10008](https://www.rfc-editor.org/rfc/rfc10008.html) (published June 2026, from `draft-ietf-httpbis-safe-method-w-body`). It provides safe, idempotent request semantics like `GET`, but carries the query in the request body — the long-standing answer to "GET with a body" / oversized query strings.

OpenAPI 3.2.0 already supports it as a **first-class path-item operation** (`query:`), alongside the new `additionalOperations` field.

TypeSpec currently cannot express this method:

- `HttpVerb` in `@typespec/http` is `"get" | "put" | "post" | "patch" | "delete" | "head"` ([types.ts](https://github.com/microsoft/typespec/blob/main/packages/http/src/types.ts)) — no `query`.
- Notably, the OpenAPI 3.2 **document model** in `@typespec/openapi3` already includes it: `OpenAPIHttpMethod3_2 = OpenAPI3HttpMethod | "query"` plus `additionalOperations` on `OpenAPIPathItem3_2` (types.d.ts). So the emitter-side representation exists — the gap is purely on the authoring side (verb decorator + `HttpVerb`), and presumably the converter/emit wiring.

Since `@typespec/openapi3` can already emit `openapi: 3.2.0` documents (`openapi-versions: [3.2.0]`), this seems like a natural, well-scoped completion of the existing 3.2 support.

## Describe the solution you'd like

1. Add `"query"` to `HttpVerb` in `@typespec/http`.
2. Add a verb decorator. Naming needs design input, since `@query` is already the query-*parameter* decorator in the same namespace. Options: `@httpQuery`, or a generic escape hatch like `@verb("query")` (which would also serve issue #2866 for `OPTIONS`, and future methods via OpenAPI 3.2 `additionalOperations`).
3. Emission rules in `@typespec/openapi3`:
- Target `3.2.0`: emit as first-class `query:` operation.
- Targets `3.0.x` / `3.1.x`: report a diagnostic (these versions have a closed operation set; `additionalOperations` is 3.2-only).
4. (Optional, symmetric) `tsp-openapi3` convert: map `query:` operations in 3.2 documents back to the new verb.

Related: #2866 (OPTIONS verb support, `design:needed`) — a generic `@verb(...)` design could resolve both, though QUERY differs in that it deserves first-class treatment given its RFC status and first-class OpenAPI 3.2 slot.

I'm happy to contribute the implementation once the decorator naming/design is settled.

## Checklist

- [x] Follow our [Code of Conduct](https://github.com/microsoft/typespec/blob/main/CODE_OF_CONDUCT.md)
- [x] Read the [docs](https://typespec.io/docs).
- [x] Search for [existing issues](https://github.com/microsoft/typespec/issues) to avoid creating duplicates.

Contributor guide

Open the contributing guide

Research direction

Begin with packages/http/src/types.ts and the @typespec/openapi3 types.d.ts model, then trace the existing verb decorator and converter/emitter wiring. Confirm how HTTP verbs reach OpenAPI path-item operations and where version-specific diagnostics are tested. Done means QUERY is authorable, emits as query for OpenAPI 3.2, and is diagnosed for earlier versions.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi, typescript
Domain
api, backend-api-design
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.