現代のREST API、GETリクエストによるGraphQL、およびWebhookエンドポイントでは、複数値の配列、ネストされたフィルタオブジェクト、Base64カーソル、URLエンコードされた検索フレーズを単一のクエリ文字列や application/x-www-form-urlencoded リクエストボディに詰め込むことが一般的です。これらのペイロードをフラットな生の文字列のまま確認・編集しようとすると、%26 エスケープの破損やブラケットの不一致を招きやすくなります。
例えば、+ でエンコードされた空白、重複キー、ネストされたブラケットフィルタ、パーセントエンコードされた = パディングを含むBase64ページネーションカーソル、および値なしのフラグパラメータを組み合わせたAPI検索クエリを考えてみましょう。
?q=distributed+tracing&tag=otel&tag=grpc&filter[status]=open&filter[priority]=high&cursor=eyJpZCI6NDIwfQ%3D%3D&dry_run
この文字列をパースすると、可読性が高く厳密に構造化されたJSON表現が即座に得られます。
{
"q": "distributed tracing",
"tag": [
"otel",
"grpc"
],
"filter": {
"status": "open",
"priority": "high"
},
"cursor": "eyJpZCI6NDIwfQ==",
"dry_run": ""
}
パーセントデコードよりもデリミタ分割を先に行うべき理由
cursor=eyJpZCI6NDIwfQ%3D%3D が "eyJpZCI6NDIwfQ==" へと綺麗にデコードされている点に注目してください。パーサーはまず生の文字列を & で分割し、各ペアを最初のリテラル = で分割し、その後で初めて + と %XX シーケンスをデコードします。もし単純なスクリプトで & や = で分割する前にクエリ文字列全体に対して decodeURIComponent() を実行してしまうと、エスケープされたアンパサンドを含むパラメータ値(R%26D -> R&D)が2つの不正なパラメータに分裂してしまいます。
JSONビューとキー・バリュー表は双方向にリアルタイム同期されるため、アプリケーションコードからJSONフィルタオブジェクトを貼り付けて、HTTPリクエストにそのまま使える適切にエスケープされたクエリ文字列を即座に生成することも可能です。