Proxyman が HTTP QUERY メソッドに対応しました

API は、データを検索したりフィルタしたりする必要があることがよくあります。小さな検索であれば、GET リクエストで十分なことがほとんどです。しかし、検索条件が多くなると、URL が長くなって読みにくく、管理も難しくなります。

新しい HTTP メソッドとして QUERY が登場しました。これは API に対して、「データを探してください。ただし、何も変更しないでください」と伝えるための明確な方法です。

Proxyman は、アプリ全体で QUERY リクエストに対応しました。手動で作成したり、キャプチャした通信で確認したり、件数の多いリストから絞り込んだり、普段使っているデバッグツールと組み合わせたりできます。

1. HTTP QUERY メソッドとは？

QUERY は、サーバーにデータの検索、フィルタ、選択を依頼するための新しい HTTP メソッドです。クエリの詳細は、URL ではなくリクエストボディに送信されます。

重要なのは、QUERY リクエストが読み取りのためのものだということです。データの作成、更新、削除は行わず、必要であれば再送しても安全です。

このメソッドは RFC 10008 で定義されています。ほかの HTTP メソッドと同じく、API サーバーがサポートを選択している場合にのみ動作します。

GET や POST との違い

GET、QUERY、POST はいずれも API に入力を送信できます。違いは、入力を送る場所と、そのメソッドがリクエストについて何を示すかです。

GET は検索値を URL に入れます。ブックマークしたり共有したりしたくなるような小さなリクエストに向いています（例：/products?brand=Proxyman&sort=price）。
QUERY は検索値をリクエストボディに入れます。多くのフィルタを使う詳細な検索に適しており、リクエストが読み取り専用であることをサーバーに伝えます。
POST もリクエストボディでデータを送信します。注文の送信など、データを作成または変更することがよくあります。API は検索に POST を使うこともできますが、そのメソッドだけでは、データを変更するかどうかはわかりません。

要するに、URL で行う小さな検索には GET、読み取り専用の詳細な検索には QUERY、作成または変更を伴う操作には POST を使います。

cURL の簡単な例

多くのフィルタを使って商品を検索できるオンラインストアを想像してください。次のリクエストは、在庫のあるワイヤレスヘッドホンを価格順に並べて取得するものです：

curl --request QUERY 'https://api.example.com/products/search' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "text": "wireless headphones",
    "filters": {
      "inStock": true
    },
    "sort": "price"
  }'

--request QUERY の部分は HTTP メソッドを指定します。その下の JSON が検索の入力で、Content-Type はそれが JSON であることをサーバーに伝えます。

GET の場合は、同じ検索内容を URL に収める必要があります。フィールドが多いと、扱いにくくなることがあります。

すべての API が QUERY に対応しているとは限りません。サーバーが対応していない場合、405 Method Not Allowed が返されることがあります。このレスポンスは Proxyman ではなく、API サーバーから返されたものです。

2. Proxyman で QUERY リクエストを作成する

Compose ツールから QUERY リクエストを直接送信できるようになりました。新しいエンドポイントを試したいとき、レスポンスを確認したいとき、GET や POST リクエストの結果と比較したいときに便利です。

Proxyman で Compose を開きます。
メソッドのメニューから QUERY を選択します。
API の URL を入力します。
API に必要なヘッダーを追加します。JSON リクエストの場合は、通常 Content-Type: application/json です。
Body タブに検索の入力を入力します。
Send をクリックし、右側のレスポンスを確認します。

スクリーンショットは 405 Method Not Allowed のレスポンスを示しています。これは、Proxyman が QUERY を送信した一方で、選択したエンドポイントがそれに対応していないことを示しています。成功するレスポンスを得たい場合は、QUERY のサポートが明記されているエンドポイントを使用してください。

3. QUERY の通信をすばやく見つける

アプリが QUERY を使い始めると、多くの GET や POST リクエストの中に紛れて見逃しやすくなります。Proxyman は Method 列に QUERY を表示するので、一目で見分けられます。

QUERY だけに絞り込むには、フィルタバーを開き、Method を QUERY に設定します。すると、Proxyman は一致するリクエストだけを表示するので、確認や比較がしやすくなります。

検索画面をテストするときに特に便利です。条件を変えて検索をやり直せば、関係のない通信を探さなくても、対応するリクエストをすぐに確認できます。

4. QUERY を既存のデバッグツールで使う

QUERY は Compose やフィルタだけに限られません。Proxyman は、メソッドが影響する場面であればどこでも QUERY を認識するため、普段のデバッグの流れにそのまま組み込めます。

リクエストの詳細： キャプチャしたリクエストで QUERY を確認し、ほかのメソッドと同じように、ヘッダー、クエリの値、ボディ、レスポンスを読めます。
Debugging Tools： メソッドでリクエストを照合できるツールでは、QUERY を選ぶと、そのルールを検索リクエストだけに適用できます。GET や POST の通信はそのまま残せます。
Scripting： QUERY リクエストに対してのみスクリプトを実行できます。ローカルでのテスト中に、検索の入力を確認したり、テスト用のヘッダーを追加したり、レスポンスを変更したりする場合に便利です。
Breakpoint： QUERY リクエストをサーバーに届く前に一時停止できます。検索の入力を確認または編集してから送信し、結果を確認できます。

これらの機能を使えば、ルールやスクリプトを、テストしたいリクエストだけに正確に適用できます。更新や決済のリクエストに影響を与えることはありません。

5. まとめと次のステップ

HTTP の QUERY メソッドにより、API の意図がより明確になります。API は、データを変更するのではなく、データを求めていることを示せます。短い URL に収めるには詳細すぎる検索を行うときに役立ちます。

Proxyman を使うと、次のことができるようになりました：

QUERY リクエストの作成と送信
QUERY 通信のキャプチャと確認
メインリストを QUERY メソッドで絞り込む
Debugging Tools、Scripting、Breakpoint で QUERY リクエストを対象にする

新しい HTTP メソッドへの対応には時間がかかります。アプリで使う前に、API のドキュメントを確認するか、まずエンドポイントを試してください。405 Method Not Allowed が返される場合、そのエンドポイントはまだ QUERY に対応していません。

サーバーだけでなく、アプリからサーバーまでの通信経路全体をテストしてください。古いゲートウェイ、ファイアウォール、クライアントライブラリは、知らないメソッドを拒否することがあります。また、自分のシステムにおけるリトライとキャッシュの動作も確認してください。このメソッドはリクエストが読み取り専用であることを示しますが、通信経路の各部分が正しく処理する必要があります。

Proxyman を最新の状態に保てば、より多くの API が QUERY を採用しても、その通信を確認してデバッグできます。詳しくは、RFC 10008 を読むか、Proxyman ドキュメントをご覧ください。