HTTP QUERY Method: Solving Complex API Queries with RFC 10008

RFC 10008は、リクエストボディを必要とする複雑な読み取り専用操作を実行するための標準化された方法を提供するために、新しいHTTP QUERYメソッドを定義しています。これにより、GETクエリパラメータの制限と、データ取得のためにPOSTを使用することのセマンティックな不正確さとの間で長年続いていた緊張関係が解消されます。

Why the HTTP QUERY Method is Necessary

HTTP QUERYメソッドが必要とされる理由は、既存のメソッドでは、技術的な安定性やAPIのセマンティクスを損なうことなく、複雑なリレーショナルクエリや深くネストされたデータ構造を効率的に扱うことができないためです。

Limitations of GET

GETはデータ取得の標準ですが、URL内のクエリパラメータに依存しています。このアプローチは、いくつかのシナリオで失敗します：

• URL Length Limits: 複雑なフィルタは、ブラウザやサーバーの文字数制限を超える巨大なURLを作成する可能性があります。
• Encoding Overhead: 非ASCII文字や特殊文字はエンコードが必要であり、リクエストサイズが増大します。
• Security and Logging: リクエストパラメータはサーバーやミドルウェアによってログに記録されることが多く、機密データが露出する可能性があります。
• Lack of Structure: URL内で配列や深くネストされた構造を表現するための普遍的な標準が存在しません（例：?roles[]=admin vs ?roles=admin）。

The Failure of GET with Request Bodies

どのRFCもGETリクエストにリクエストボディを含めることを明示的に禁止していませんが、強く推奨されていません。実際には、多くのクライアント、プロキシ、およびWebサーバーはGETボディを不整合に扱います。一部は完全に拒否し、他のものはボディを全体的に破棄します。このため、ボディを伴うGETは、本番環境において信頼できない選択肢となります。

The Semantic Issues with POST

開発者は、クエリのためにリクエストボディを送信するために、回避策としてPOSTをよく使用します。しかし、POSTは非冪等（non-idempotent）として定義されており、リソースの作成または処理を目的としています。これにより、いくつかの問題が発生します：

• Retries: POSTは冪等ではないため、失敗時の自動リトライはリスクを伴います。
• Caching: プロキシやミドルウェアは、POSTリクエストを読み取り専用として自動的に識別できないため、標準的なキャッシュメカニズムの使用が妨げられます。

Technical Specifications of the QUERY Method

QUERYメソッドは、GETと機能的に同様に設計されていますが、明示的にリクエストボディをサポートしています。その主な特徴は以下の通りです：

• Safety and Idempotency: GETと同様に、QUERYは安全かつ冪等（idempotent）として定義されており、サーバーの状態を変更しないことを意味します。
• Cacheability: QUERYリクエストはキャッシュ可能です。ただし、実装においては、異なるクエリパラメータに対して正しいデータがreturnedされることを確実にするために、リクエストボディをキャッシュキーに組み込む必要があります。

Implementation Considerations and Gotchas

標準化されたものの、QUERYメソッドはすべての検索エンドポイントの直接的な置き換えにはなりません。開発者は以下の制約を考慮すべきです：

• Limited Ecosystem Support: QUERYのサポートは現在限定的です。多くのプロキシ、ファイアウォール、およびWebサーバーは、依然としてこのメソッドを拒否する可能性があります。例えば、Kreya APIクライアントはバージョン1.20でサポートを追加しましたが、広範範な普及には数年かかる可能性があります。
• Linkability: QUERYリクエストは、クエリパラメータがURLではなくリクエストボディに存在するため、ブックマークしたり、単純なURLで共有したりすることはできません。
• Caching Complexity: QUERYのためのカスタムキャッシュの実装は、GETよりも複雑です。なぜなら、キャッシュキーはリクエストボディから派生させる必要があるからです。

Community Perspectives and Critiques

エンジニア間の議論は、明示的な標準を重視する層と、既存の慣習に従うことを好める層との間で分断されています。

Arguments for the New Method

一部の意見では、明示的なメソッドを持つことが前進するための唯一の正しい方法であると主張されています。ボディを伴うGETは、標準化されるべきではない「ハック」であると考えています。

Arguments Against the New Method

批判的な意見では、標準はボディを伴うGETという既存の慣習に従うべきであったと示唆されており、新しい動詞を導入することはレガシーなインフラストラクチャとの問題を引き起こす可能性があると主張しています。あるユーザーは、HTTP/1.1のみをサポートする高価なSSLインターセプトプロキシアプライアンスが未知のHTTP動詞に遭遇した際のリスクとして「DoS by the track record」を指摘しました。

他の開発者は、リクエストボディをサポートするためだけに新しいメソッドを追加することが、HTTP仕様の長期的な関連性を維持するための最善の方法であるかどうかを疑問視しており、それが堅牢な設計ではなく、抵抗の少ない経路を選択しただけである可能性を示唆しています。