HTTP QUERYメソッドとは？RFC 10008とQUERY・GET・POSTの違いを解説

HTTP QUERYメソッドは、RFC 10008（2026年6月）で定義された新しいリクエストメソッドで、クエリをリクエストボディで送信し、安全かつ冪等です。ボディ付きのGETと考えることができます。複雑なフィルタのためのPOSTの余地と、キャッシュと自動再試行のためのGETの保証が得られます。

3 KBのフィルタをURLに詰め込んだことがあるなら、あるいは読み取り専用の検索をPOSTで送信して、キャッシュと再試行ロジックがそれを無視するのを見たことがあるなら、QUERYが解決策です。このガイドでは、仕様が何を述べているか、QUERYがGETやPOSTとどう比較されるか、今日何がそれをサポートしているか、そしてコーディングエージェントでQUERYエンドポイントをテストする方法を説明します。

HTTP QUERYメソッドとは何か？

QUERYは、リクエストコンテンツに記述されたクエリを実行し、結果を返すようターゲットリソースに要求するHTTPメソッドです。リクエストボディとそのContent-Typeがクエリを定義します。このメソッドは安全（クライアントは状態変化を期待しない）かつ冪等（繰り返しても同じ効果）であるため、クライアント、プロキシ、キャッシュはGETと同様に再試行およびキャッシュできます。

仕様はRFC 10008「The HTTP QUERY Method」で、2026年6月にJulian Reschke（greenbytes）、James M. Snell（Cloudflare）、Mike Bishop（Akamai）によって公開されたProposed Standardです。IANAはこれをHTTP Method Registryに「safe: yes, idempotent: yes」として追加し、WebDAV時代のSEARCHメソッド（QUERYがほとんどそうなりかけたもの）のすぐ隣に置きました。

QUERYリクエストは次のようになります：

QUERY /contacts HTTP/1.1
Host: example.org
Content-Type: application/x-www-form-urlencoded
Accept: application/json

select=surname,givenname,email&limit=10&match=%22email=*@example.*%22

サーバーは200 OKとボディに結果を返して応答します。

なぜGETとPOSTでは不十分だったのか

QUERY以前は、複雑な読み取りには2つの選択肢があり、どちらも漏れがありました。

GETはすべてをURLに置きます。 RFC 10008はそれに関する4つの問題を挙げています：

サイズ制限は事前に不明です。なぜならリクエストは多くのシステムを通過するからです。RFC 9110は、送信者と受信者が少なくとも8,000オクテットをサポートすることを推奨しているだけです。
構造化データを有効なURIにエンコードするのは無駄です。
URIはリクエストボディよりもはるかに頻繁にログに記録され、ブックマークされるため、機密性の高いフィルタにとってプライバシー問題となります。
クエリ入力のすべての組み合わせが独自のリソースになります。

ボディ付きGETも答えではありません。 RFC 9110は、GETリクエストのコンテンツには定義されたセマンティクスがないと述べています。サーバーによってはそれを読み取り、サーバーによってはそれを破棄し、プロキシによってはリクエストを拒否します。パス全体でそれを当てにすることはできません。

POSTは機能しますが、意図について嘘をつきます。 POST検索は問題なく実行されますが、その操作が読み取り専用であることをクライアント、キャッシュ、プロキシ、再試行ライブラリに伝えるものは何もありません。そのため、キャッシュはそれをスキップし、クライアントは接続が切断された後に再試行しません。再試行を安全にするためだけに、純粋な読み取りに冪等キーを付けざるを得なかったなら、この問題を感じたことがあるでしょう。

QUERYはPOSTのボディを維持し、GETの保証を追加します。

QUERYとGETとPOSTの比較

RFC 10008の表1に基づく比較は次のとおりです：

プロパティ	GET	QUERY	POST
安全	はい	はい	潜在的にいいえ
冪等	はい	はい	潜在的にいいえ
リクエストボディ	定義されたセマンティクスなし	期待され、クエリを定義する	期待される
クエリ自体のURI	はい、定義により	オプション、`Location`経由	いいえ
結果のURI	オプション、`Content-Location`経由	オプション、`Content-Location`経由	オプション、`Content-Location`経由
キャッシュ可能	はい	はい、ボディはキャッシュキーの一部	後続のGETまたはHEADのみ
ブラウザからのCORSプリフライト	単純リクエストには不要	常に	単純リクエストには不要

要約すると、クエリがURLに無理なく収まる場合はGETを、収まらない場合はQUERYを、リクエストが状態を変更する場合にのみPOSTを使用します。古典的なメソッドの復習については、HTTPメソッドとGET vs POSTのガイドをご覧ください。

RFC 10008が定義するもの

Content-Typeは必須

サーバーは、Content-Typeが欠落しているかボディと矛盾するQUERYを失敗させなければなりません（MUST）。RFCはこれらのステータスコードを推奨しています：

400 Bad Request：メディアタイプがない、またはコンテンツと一致しないタイプ。サーバーはボディをスニッフィングして上書きすることはできません。
415 Unsupported Media Type：リソースがそのクエリ形式をサポートしていません。
422 Unprocessable Content：形式は問題ないがクエリを実行できない。たとえば、存在しないテーブルを指定したSQLなど。
406 Not Acceptable：クライアントが、リソースが生成できない応答タイプを要求しました。

LocationとContent-Location

サーバーは、QUERYを後でGETできるものに変える2つのオプションヘッダーを返すことができます：

Content-Locationは、この特定の実行の保存された結果を指します。一時的なものである可能性があります。
Locationは、保存されたクエリ自体を指します。それに対するGETは、ボディを再送信することなく、新しいデータでクエリを再実行します。

RFCは、GETのキャッシュの方が単純であるため、繰り返しリクエストにはLocation URIへのGETに切り替えることをクライアントに提案しています。機密データを含むクエリに対してどちらかのヘッダーを返す場合、URIは元のボディの機密部分を含むべきではありません（SHOULD NOT）。

キャッシュ

QUERY応答はキャッシュ可能です。キャッシュキーは、リクエストコンテンツと、メディアタイプなどの関連メタデータを含まなければなりません（MUST）。キャッシュは、より多くのヒットを得るために、たとえばコンテンツエンコーディングを削除したり、+jsonタイプのJSONを正規化したりして、最初にボディを正規化してもよい（MAY）。仕様は、不適切な正規化が誤った応答を返す可能性があると警告しているため、CDNはここで注意することが予想されます。

リダイレクト

301、302、307、または308は「同じQUERYを新しいURIに送信する」ことを意味します。POSTとは異なり、QUERYは301または302でGETに書き換えてはなりません。303 See Otherは「このURIでGETを使用して結果を取得する」ことを意味します。

Accept-Queryヘッダー

Accept-Queryは、QUERYサポートとリソースが受け入れるクエリ形式を通知する新しい応答ヘッダーです。これはStructured Fieldリストであるため、そのように解析します：

Accept-Query: "application/jsonpath", application/sql;charset="UTF-8"

クライアントは、OPTIONSでサポートを発見し、Allowヘッダーを読むことも、単にQUERYを送信して405 Method Not Allowedを処理することもできます。

今日どのツールがQUERYをサポートしているか？

サポートは不均一であるため、独自のスタックをテストしてください。2026年10月28日に確認した内容は次のとおりです：

ツール	結果
Node.js 24 `http`サーバー	`http.METHODS`に`QUERY`が含まれる；プレーンサーバーがメソッドとボディを受信した
Node.js 24 `fetch`	JSONボディでQUERYを送信した
curl 8.7	`-d`付きの`curl -X QUERY`がメソッドとボディを送信した
Python 3.14 `http.client`	ボディ付きでQUERYを送信した
OpenAPI 3.2	Path Item ObjectにQUERY操作用の`query`フィールドがある
Apidog CLI 2.2.12	`endpoint-create`スキーマが`"method": "query"`を受け入れる

ローカルのNodeサーバーに対して使用したcurl呼び出しは次のとおりです：

curl -i -X QUERY http://localhost:3000/products \
  -H "Content-Type: application/json" \
  -d '{"q":"running shoe","limit":2}'

Fetch StandardはGETとHEADでのボディのみを禁止しているため、ブラウザはボディ付きでQUERYを送信できます。ただし、QUERYはCORSセーフリストされたメソッドではないため、クロスオリジンのQUERYはすべてプリフライトをトリガーします。サーバーはAccess-Control-Allow-MethodsにQUERYをリストする必要があります。

ギャップはネットワークの途中にあります：メソッドを許可リストに登録したり、キャッシュをボディでキー付けしないリバースプロキシ、APIゲートウェイ、WAF、CDNです。出荷前に各ホップを確認してください。APIs You Won’t Hateニュースレターは、多くのWebフレームワークがすでにQUERYを直接またはカスタムメソッドルーティングを通じて処理していると指摘しています。

クライアントを壊さずにQUERYを採用する方法

POST検索エンドポイントを撤去する必要はありません。

POSTルートと並行してQUERYを追加します。 両方を同じハンドラーに向けます。新しいクライアントはQUERYを使用し、古いクライアントは引き続き機能します。
それを通知します。 リソースでAccept-Queryを返し、OPTIONSおよび405応答のAllowにQUERYを含めます。
Content-Typeを強制します。 RFCが推奨するように400または415を返し、解析はできるが実行できないクエリには422を返します。
405または501にフォールバックします。 ホップがQUERYを拒否した場合、クライアントは同じボディをPOSTとして再試行する必要があります。
CORSを修正します。 ブラウザクライアントのためにAccess-Control-Allow-MethodsにQUERYを追加します。
キャッシュについて決定します。 キャッシュがボディでキー付けされる場合にのみ共有キャッシュを有効にします。そうでなければ、Location URIを返し、クライアントにGETさせます。
文書化します。 OpenAPI 3.2では、パスアイテムのquery:の下で操作を定義します：

openapi: 3.2.0
paths:
  /products:
    query:
      summary: Search products
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductQuery'
      responses:
        '200':
          description: Matching products

短く単純なフィルタは、GETのクエリ文字列として残すことができます。RFC 10008自体、クエリがそれほど短い場合はGETの方がおそらく良い選択であると述べています。

コーディングエージェントにApidog CLIでQUERYエンドポイントをテストさせる

新しいメソッドとは、ハッピーパス、すべてのエラーコード、フォールバックルートをチェックすることを意味します。それをClaude Code、Codex、またはCursorに任せ、Apidog CLIを操作させます。

CLIをインストールし、ログインし、エージェントにApidogスキルを追加します：

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

次に、エージェントに1つのプロンプトを与えます：

In Apidog project <projectId>, add a QUERY /products endpoint that takes a
JSON body {q, limit}. Create test cases that assert 200 with an array for a
valid body, 415 for Content-Type text/plain, and 400 with no Content-Type.
Run them against the staging environment and summarize any failures.

エージェントは各スキーマを読み取り、そのペイロードを検証し、その後にのみ書き込みます：

apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file endpoint.json
apidog endpoint create --project <projectId> --file endpoint.json
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> -r cli,json

書き込むendpoint.jsonは"method": "query"を設定します。これはCLIのendpoint-createスキーマがget、post、およびWebDAVメソッドと並んでリストしています。Apidogアプリで実行を確認するには--upload-reportを追加します。同じapidog runコマンドに-r junitを付けるとCIに組み込めます。詳細はapidog runでCIでAPIテストを実行する方法とClaude CodeでApidog CLIを使用する方法をご覧ください。Apidogの無料プランは最大4ユーザーまでカバーします。

FAQ

HTTP QUERYメソッドは公式標準ですか？ はい。RFC 10008は2026年6月に公開されたStandards TrackのProposed Standard RFCであり、IANAはQUERYをHTTP Method Registryに安全かつ冪等としてリストしています。

QUERYは単なるボディ付きGETですか？ 近いですが、より適切に定義されています。RFC 9110はGETボディにセマンティクスを与えていないため、中間者はそれを無視または拒否できます。QUERYはボディをクエリにし、Content-Typeを要求し、ボディをキャッシュキーに折り込みます。

POSTの代わりにいつQUERYを使用すべきですか？ URLには大きすぎる、または機密性が高すぎる読み取り専用の検索やフィルタにはQUERYを使用します。何かを作成または変更するリクエストにはPOSTを使用し続けます。

ブラウザはQUERYリクエストを送信できますか？ はい、カスタムメソッドでfetchを通じて送信できます。クロスオリジンのQUERYリクエストは常にCORSプリフライトが必要なため、サーバーはそのメソッドを許可する必要があります。

QUERY応答はキャッシュされますか？ キャッシュされる可能性があります。キャッシュはリクエストボディとそのメタデータをキャッシュキーに含めなければなりません。多くのCDNとプロキシはまだそうしていないため、確認するか、クライアントがGETできるLocation URIを返してください。

OpenAPIはQUERYをサポートしていますか？ OpenAPI 3.2は、QUERY操作用にPath Item Objectにqueryフィールドを追加しているため、拡張なしで文書化できます。