REST API における URL エンコーディングのベストプラクティス

なぜ API において URL エンコーディングが重要なのか

適切な URL エンコーディングは、REST API 開発において極めて重要です。エンコードが正しく行われていない URL は、リクエストの失敗やセキュリティ上の脆弱性、データの欠損、さらには異なるシステムやプログラミング言語間での相互運用性の問題を引き起こしかねません。API 開発者としては、リクエストを送信する際に URL をどうエンコードするか、そしてリクエストを処理する際にどうデコードするかの両方を理解しておく必要があります。

パスパラメータのエンコーディング

REST API では、リソースを識別するためにパスパラメータがよく使われます。これらのパラメータに特殊文字が含まれる場合、適切なエンコーディングが不可欠です。

// 特殊文字を含むパスパラメータ
// リソース: "Tom & Jerry's Show"
GET /api/shows/Tom%20%26%20Jerry%27s%20Show

// JavaScript を使う場合
const showName = "Tom & Jerry's Show";
const url = `/api/shows/${encodeURIComponent(showName)}`;

// 値にスラッシュを含むパス
// ファイル: "documents/my report.pdf"
GET /api/files/documents%2Fmy%20report.pdf

クエリパラメータのエンコーディング

クエリパラメータは、エンコーディングの問題が最も発生しやすい箇所です。キーと値の両方を必ずエンコードしましょう。

// 特殊文字を含む複数のパラメータ
GET /api/search?q=C%2B%2B%20programming&category=languages%20%26%20tools&page=1

// URLSearchParams を使う場合（推奨）
const params = new URLSearchParams({
  q: 'C++ programming',
  category: 'languages & tools',
  page: '1'
});
const url = '/api/search?' + params.toString();

クエリ文字列における配列とオブジェクトの扱い

配列パラメータの扱い方は、API フレームワークによって異なります。以下によく使われる慣習を示します。

// キーを繰り返す方式（最も一般的）
GET /api/items?tag=javascript&tag=typescript&tag=react

// ブラケット記法（PHP、Rails）
GET /api/items?tags[]=javascript&tags[]=typescript

// カンマ区切り（一部の REST API）
GET /api/items?tags=javascript,typescript,react

// ネストしたオブジェクト（ブラケット記法）
GET /api/search?filter[status]=active&filter[sort]=date

Content-Type とエンコーディング

Content-Type ヘッダーは、リクエストボディのデータがどのようにエンコードされるかを決定します。

• application/x-www-form-urlencoded - URL のクエリ文字列に似た形式。キーと値がエンコードされ、スペースは + になります
• multipart/form-data - ファイルアップロードに使われます。各パートがそれぞれ独自のエンコーディングを持ちます
• application/json - JSON 形式。ボディに URL エンコーディングは不要ですが、Content-Type を正しく設定する必要があります

API のセキュリティに関する考慮事項

• デコードした URL パラメータは、サーバー側で必ず検証・サニタイズすること
• %2e%2e%2f（../）のようなエンコードされたシーケンスによるパストラバーサル攻撃に注意すること
• サービス拒否（DoS）攻撃を防ぐため、URL の長さ制限を実装すること
• クライアント側のエンコーディングを決して信用せず、サーバー側で必ず再検証すること
• 悪意ある入力が一度のデコードでフィルターをすり抜ける、二重エンコーディング攻撃に警戒すること
• URL デコード後であっても SQL インジェクションを防ぐため、パラメータ化クエリを使用すること

API における URL エンコーディングのテスト

API エンドポイントをテストする際は、以下のシナリオに対するテストケースを含めましょう。

• スペースを含むパラメータ（%20 と + の両方をテストする）
• 予約文字（&、=、?、#）を含むパラメータ
• Unicode 文字を含むパラメータ
• 空のパラメータ値
• 非常に長いパラメータ値
• すでにエンコード済みの入力（二重エンコーディングの検出）
• ヌルバイト（%00）を含むパラメータ