新しいHTTP QUERYメソッドの解説
The new HTTP QUERY method explained (kreya.app)
要約
新しいHTTP QUERYメソッドは、RFC 10008で定義されたHTTPメソッドであり、複雑なクエリにおけるGETリクエストの限界と、読み取り専用操作にPOSTを使用する際のセマンティックな問題を解決するために導入されました。このメソッドはGETに似ていますが、リクエストボディを許可し、セーフかつ冪等であり、キャッシュ可能です。複雑な検索クエリに最適なソリューションを提供しますが、まだサポートは限定的であるため、導入前には現在のサポート状況とユースケースを慎重に検討する必要があります。
全文翻訳
新しいHTTP QUERYメソッドについて
RESTful APIの世界では、私たちは長らく(自己課せられた)厳格なルールのセットに従ってきました。GETでデータを取得する場合でも、POSTでエンティティを作成する場合でも、PUTでリソースを更新する場合でも、HTTPメソッドはサーバーにあなたの意図を伝えます。
ごく最近、HTTPの新しいQUERYメソッドを定義するRFC 10008が公開されました。すでに他のHTTPメソッドがあるのに、なぜこれが必要なのでしょうか?見ていきましょう。
純粋に技術的な観点から見ると、HTTPメソッドは単なる文字列です。例えば、
GET /api/v1/users
を送る代わりに、理論的には
FETCH /api/v1/users
を使用することも可能です。実際には、GETやPOSTのようなよく知られたHTTPメソッドには、多くのRFCや暗黙的で文書化されていない動作があります。
例として、ブラウザはアドレスを入力したりブックマークをクリックしたりするとGETリクエストを送信します。標準的なHTTPフォームはGETとPOSTメソッドのみを許可します。ほとんどのプロキシ、ファイアウォール、Webサーバーは「標準」HTTPメソッドのみを許可します。
では、何十年もうまく機能してきた既存のメソッドセットがあるのに、なぜ新しいHTTPメソッドを導入する必要があるのでしょうか?
GETを使用したクエリ
従来、リソースをフィルタリングしたい場合、GETリクエストでクエリパラメータを使用しました(例: /api/v1/users?role=admin&status=active&sort=desc)。これは単純なフィルタリングにはうまく機能します。しかし、複雑なリレーショナルクエリ、深いネスト、高度なロジックを実行する必要がある場合、URLは巨大になり、読みにくくなり、時にはブラウザやサーバーの文字数制限に達することもあります。
その他の潜在的な問題点:
- 非ASCII文字や特殊文字をパラメータとして送信するにはエンコードが必要で、リクエストサイズが増加します。
- サーバーやその他のミドルウェアはリクエストパラメータをログに記録する可能性があり、状況によっては問題となることがあります。
- 配列のような一部のデータ構造の表現は、明確に定義されておらず、実装固有です(例:
?roles[0]=admin&roles[1]=reportervs?roles=admin&roles=reportervs?roles[]=admin&roles[]=reporter)。 - 同様に、深くネストされた構造の表現も問題となります。
これらはすべて、データをクエリパラメータとして送信することの欠点であるため、JSONリクエストボディを持つGETリクエストを単純に送信してはどうでしょうか?理論的には、これは機能するはずです。HTTP RFCのどれも、HTTP GETリクエストでリクエストボディを使用することを明確に禁止していませんが、そうすべきではないと示唆しています。その結果、さまざまなクライアント、プロキシ、Webサーバーの実装が、ボディを持つGETリクエストを異なる方法で処理します。一部は即座に拒否し、一部はボディを単純に削除し、一部はそれを解釈します。
このため、リクエストボディを持つHTTP GETの使用は悪い考えです。例えば、企業のファイアウォールや異なるブラウザの後ろにいるユーザーは、あなたのウェブサイトを使用できなくなる可能性があります。これも、GETリクエストがリクエストボディをサポートするようになったと指定する新しいRFCがない理由です。それは多くの既存の実装を壊すでしょうから。
回避策: POSTを使用したクエリ
GETでリクエストボディを送信すると問題が発生する可能性があるため、回避策はPOSTを使用することです。
POSTはリクエストボディを許可しますが、重大な意味論的な問題を引き起こします。POSTは冪等でないと定義されており、リソースの作成または処理を目的としています。
これは大きな問題ではないように聞こえるかもしれませんが、例えば失敗時の自動リトライを実装する際には煩わしいことがあります。GETメソッドは安全で冪等であると定義されているため、サーバーの実装が正しければ、副作用を心配することなく失敗したリクエストをリトライできます。また、プロキシやその他のミドルウェアが、操作が読み取り専用であることを自動的に理解することを不可能にします。例えば、ミドルウェアはGETリクエストを一定期間自動的にキャッシュするかもしれませんが、これはPOSTリクエストでは機能しません。
QUERYメソッド
上記すべての理由により、長年の議論を経てQUERYメソッドが指定されました。QUERYメソッドは特別なものではなく、RFCはおおよそGETメソッドに似ているがリクエストボディを持つと述べています。安全で冪等であることを意図しています。
QUERYリクエストはキャッシュ可能ですが、実装者はリクエストの内容をキャッシュキーに含めるように注意する必要があります。全体として、複雑な検索クエリにふさわしいHTTPメソッドがついに提供されました。
[画像: Kreya screenshot of sending a QUERY request]
QUERYの注意点
すべての検索関連のエンドポイントをすぐにQUERYに切り替えたくなるかもしれません。そうする前に、考慮すべきことがいくつかあります。
- HTTP QUERYのサポートはまだ非常に限られており、しばらくの間そうかもしれません。完全にサポートされるまでには何年もかかる可能性があります。例えば、Kreyaは最近の1.20リリースでHTTP QUERYのサポートを標準で追加しました(ただし、それ以前からカスタムHTTPメソッドを送信することは可能でした)。他のクライアント、プロキシ、Webサーバーはまだそれを拒否する可能性があります。
- URLパラメータにデータを持つ標準のGETクエリは、依然として完全に問題ありません。それらをQUERYメソッドに変更する緊急の必要がない場合は、そのままにしておいてください。
- ユーザーがフィルタリングされたデータのリンクを共有したりブックマークしたりできるようにしたい場合は、GETリクエストを使い続けてください。QUERYリクエストとしてリンクを共有することは機能しません。
- QUERYリクエストのカスタムキャッシュの実装は、リクエストボディを考慮する必要があるため、GETリクエストよりも困難です。
結論
要するに、HTTP QUERYは読み取り専用リクエストに対してPOSTを置き換えます。すべてで完全にサポートされるまでには時間がかかるかもしれませんが、通常のGETリクエストがユースケースで十分でない場合は、それを検討(およびテスト!)すべきです。