サーバーと通信してデータを検索・絞り込むときは、GET のクエリパラメーターか、POST のリクエストボディを使って条件を指定することが一般的です。2026年6月に、その中間を担う QUERY メソッドが RFC 10008 として標準化されました。

QUERY は、リクエストボディ（JSONなど）に検索条件を含められる一方で、サーバーの状態を変更しない安全で冪等なメソッドです。「冪等」ってなんて読むんだろうと調べたら「べきとう」と読むらしいです。

数学や情報工学で使われる言葉だそうで文系エンジニアの私が知らなかったのは当然と言えます。冪等性は「同じ操作を何度繰り返しても結果が変わらない性質」だそうですが、今回のFetchAPIで考えると、「何回同じ操作をしてもサーバーやデータを変更/ 更新したりすることはない」と理解しておけば良さそうです。

複雑な検索条件を送るために POST を使っていた場面で、検索であることをHTTPの意味として表現しやすくなります。

ただし、標準化されたばかりであり、既存のサーバー、CDN、リバースプロキシ、APIフレームワークが期待どおりに扱えるとは限りません。この記事では、Fetch APIでの基本的な使い方と、事前に確認しておきい点をまとめます。

HTTP QUERYメソッドとは

QUERY は、リクエスト先のリソースに対して、リクエストボディで渡した条件を処理し、その結果を返すよう求めるメソッドです。検索対象は、APIが公開するコレクション、データベース、検索インデックスなど、サーバー側で定義します。

意味としては「取得するが、検索条件はURLではなくリクエストボディに入れる」という位置付けです。QUERY は安全であり、リクエスト自体がサーバーの状態を変えることを意図しません。また冪等でもあるため、通信失敗時に同じリクエストを再試行しても、処理が重複してデータを変更することはありません。

なお、QUERY は GET の完全な置き換えではありません。短く共有しやすい条件であれば、URLとして表現できる GET が引き続き適しています。

Fetch APIでの基本的な使い方

Fetch APIでは、method に QUERY を指定して送信します。コーヒー検索条件をJSONで送る例は次のとおりです。’POST’ を ‘QUERY’ にしただけですね。

const response = await fetch('/api/products/search', {
  method: 'QUERY',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    category: 'coffee',
    minPrice: 1000,
    inStock: true,
  })
});
const products = await response.json();

リクエストボディを持つため、Content-Type を明示します。RFC 10008では、QUERY のリクエストに内容がある場合、サーバーはその形式を Content-Type から判断します。

GET・POSTとの違い

観点	GET	QUERY	POST
主な用途	URLが指すリソースの取得	条件を渡して安全に検索・照会する	送信・作成・処理依頼など
リクエストボディ	意味が定義されていないため使わない	検索条件を入れられる	送信データを入れられる
安全性	安全	安全	安全とは限らない
冪等性	冪等	冪等	冪等とは限らない
URL共有・ブックマーク	しやすい	ボディはURLに含まれないため、そのままではしにくい	しにくい
標準上のキャッシュ可能性	可能	可能。ただしボディを含めたキャッシュキーが必要	可能な場合もあるが、一般的な共有キャッシュでは扱いにくい

QUERYを使うメリット

複雑な検索条件をURLに詰め込まなくてよい

多数のフィルター、配列、入れ子の条件などをURLクエリパラメーターで表すと、長く読みにくくなります。

URLの長さには、ブラウザ・サーバー・プロキシなど経路ごとの実質的な制約もあります。QUERY なら、JSONなどで構造を保ったまま条件を送れます。

POSTで検索していた意図を明確にできる

複雑な検索条件を送るために POST を使うAPIは多くあります。私自身も頻繁に使います。

しかし、POST は状態変更を伴う用途にも使われるため、「検索なのか、データを変更しうるものなのか」がメソッドだけでは分かりません。

QUERY は検索・照会であり、状態を変更しないことを明示できます。

URLに条件を出しにくい場合がある

URLはアクセスログ、ブラウザ履歴、ブックマークなどに残りやすいものです。

検索条件をリクエストボディに置くことで露出範囲を減らせる場合があります。ただし、リクエストボディもサーバーのログや監視サービスに記録される可能性があるため、機密情報を安全に扱えることを保証するものではありません。

デメリットと注意点

エコシステムの対応はまだ揃っていない

QUERY は2026年6月公開の新しい標準です。Fetch APIでは任意のメソッド名を指定して送信できますが、Webサーバー、APIゲートウェイ、WAF、リバースプロキシ、CDN、監視ツール、ルーティングライブラリなどが QUERY を許可・記録・キャッシュできるかは個別に確認が必要です。

特に、許可するHTTPメソッドを限定している環境では、405 Method Not Allowed や 501 Not Implemented になることがあります。公開APIで採用する前に、開発・ステージング・本番と同じ経路で動作を確認しましょう。

クロスオリジンではCORSプリフライトが発生する

QUERY はCORSで安全とみなされるメソッドの一覧には含まれません。ブラウザから別オリジンのAPIを呼ぶ場合、実際の QUERY の前に OPTIONS によるプリフライトが発生します。

API側では、Access-Control-Allow-Methods に QUERY を含め、必要なリクエストヘッダーも許可する必要があります。単にアプリケーションのルートを実装するだけでは動かないことがある点に注意します。

HTMLフォームからは送れない

QUERY はフォーム送信では使えません。* HTMLフォームの標準送信機能だけを使って　という意味です。

キャッシュはGETほど単純ではない

QUERY のレスポンスは標準上キャッシュ可能ですが、同じURLでもリクエストボディが異なれば別の検索です。そのためキャッシュは、URLだけでなくボディと関連メタデータを考慮してキーを作る必要があります。既存のCDNやプロキシが期待どおりに対応するとは限りません。

サーバーが検索を再実行できるURLを Location ヘッダーで返せる場合、次回以降は通常の GET に切り替える設計も仕様で想定されています。

[注意点] QUERYメソッドは検索専用であり、状態変更に使わない

QUERY は安全なメソッドとして定義されています。

データの作成、更新、削除、メール送信、課金処理など、サーバー側に副作用を生む操作には使いません。こうした操作では用途に応じて POST、PUT、PATCH、DELETE などを使います。

採用を検討するなら

自分たちでクライアントとサーバー、間に置くインフラを管理できる場合は、複雑な検索APIで試す余地があります。まずは内部APIや限定的なエンドポイントで、ルーティング、ログ、認可、CORS、エラー処理、キャッシュの挙動を確認するのが現実的です。

一方、外部利用者が多い公開APIや、複数事業者のネットワーク機器を経由するAPIでは、当面は GET と POST の方が互換性を確保しやすいでしょう。QUERY を使う場合も、未対応時のレスポンスを適切に処理し、必要なら既存の POST ベースの検索エンドポイントを併設する設計を検討します。

まとめ

QUERY は、リクエストボディを使って安全・冪等な検索を表現するための新しいHTTPメソッドです。複雑な検索条件を扱いやすく、POST を検索目的で使う場合の意味を明確にできます。

ただし、ブラウザからは fetch() で送信できても、フォーム送信・CORS・サーバー・CDN・プロキシ・フレームワークまで含めた対応状況は別問題です。まずは既存の GET と POST を基本にし、QUERY が解決する具体的な課題がある場合に、利用する経路全体を検証して採用するのがよさそうです。

参考：RFC 10008: The HTTP QUERY Method／MDN: QUERY request method