HTTP QUERY メソッド

QUERY は、実際に存在するギャップを埋める提案中の HTTP メソッドです。GET と同じく**安全（safe）で冪等（idempotent）**でありながら、POST のように リクエストボディを運べます。*「ボディを送れる GET」*と考えてください。

存在理由

複雑なクエリは、長いあいだ不格好な二者択一を迫られてきました。

• GET とクエリ文字列は、すべてのフィルタを URL に詰め込みます。URL には長さ 制限があり、平文でログに記録され、構造化された条件や入れ子の条件には扱いづらい です。
• POST とボディはペイロードを問題なく運べますが、意図について嘘をつきます。 POST は安全でも冪等でもないため、キャッシュ、クローラー、中間装置はそのリクエスト が状態を変更すると仮定せざるを得ません。実際にはそうではなく、単に読み取っている だけです。

QUERY はこの緊張関係を解消します。セマンティクスが*「これは読み取りである」*と示し、 ボディが条件を運びます。

特性

リクエストの実例

QUERY /products HTTP/1.1
Host: shop.example
Content-Type: application/json
Accept: application/json

{ "category": "boots", "inStock": true }

Content-Location によるキャッシュ

QUERY は安全かつ冪等であるため、レスポンスはキャッシュできます。ただしボディが 変化するので、キャッシュキーを URL だけにすることはできません。サーバーは Content-Location ヘッダーで結果の正規の位置を示します。

HTTP/1.1 200 OK
Content-Location: /products?category=boots&inStock=true
Cache-Control: max-age=60

キャッシュ（またはクライアント）は、同等のリクエストに対してその表現を再利用できます。 これが、ボディを伴う読み取りをキャッシュ可能なまま保つための仕組みです。

試してみる

プレイグラウンドにアクセスして、このサイトのエコーエンドポイントに実際の QUERY リクエストを送信し、メソッド、ヘッダー、ボディがサーバーにどう届くかを正確に 確認してください。

QUERY は IETF Internet-Draft で定義されており、まだ進化の途上にあります。上記の 詳細は作業中の要約として扱い、権威ある最新の文面はリンク先の draft を確認して ください。