APIパラメータ完全ガイド：PathからBodyまで一気に理解

API を十分に長く開発していれば、こんな独り言を何度もつぶやいたことがあるでしょう：

「このパラメータは Path？Query？Header？Body？それとも Cookie？てか、Cookie 本当に必要？」

心配しないでください。あなただけではありません。

こうした疑問はとても一般的で、そして非常に重要です。構造のしっかりした API は、使いやすく、テストしやすく、保守もしやすくなります。良いニュースは、パラメータの配置には明確なロジックがあるということです。各パラメータの役割を理解すれば、もう迷うことはありません。

このガイドでは、API における 5 つの主要なパラメータタイプを解説し、実践的なベストプラクティスを紹介します。そして、EchoAPI のようなツールを使って、プロフェッショナルな API 設計とドキュメント作成がいかに簡単にできるかもご紹介します。

API パラメータの 5 つの基本タイプ

一般的な RESTful API では、リクエスト内での 役割 に応じて、パラメータがさまざまな場所に配置されます：

1. Path パラメータ – 特定のリソースの場所を示す
2. Query パラメータ – リクエストの条件や振る舞いを指定する
3. Header パラメータ – メタデータやコンテキスト情報を渡す
4. Cookie パラメータ – セッション管理や状態保持に使う
5. Body パラメータ – 複雑・構造化されたデータを送信する

それぞれの見た目や場所は違っても、本質的にはすべてクライアントからサーバーへの入力情報です。

ここからは、それぞれのタイプを具体例とコードとともに見ていきましょう。

1. Path パラメータ

GET /users/42

• パラメータ名：id（URL では 42 と表示されますが、ルートは /users/:id と定義されます）
• パラメータ値：42
• 場所：URL のパス部分

// Express.js での取得方法
const userId = req.params.id;

🔹 Path パラメータの典型的な使い方です。
👉 req.params は Path パラメータ 専用のオブジェクトです。
✔️ この例では、userId は req.params から取得されます。

2. Query パラメータ

GET /users?age=25&sort=desc

• パラメータ名と値：
  • age = 25
  • sort = desc
• 場所：URL の ? の後ろ

const { age, sort } = req.query;

🔹 これらは Query パラメータで、req.query を使ってアクセスします。
✔️ age と sort は req.params ではなく req.query にあります。これは柔軟な条件指定などに使われます。

3. Header パラメータ

Authorization: Bearer <token>
Content-Type: application/json

• パラメータ名と値：
  • Authorization = Bearer <token>
  • Content-Type = application/json
• 場所：HTTP リクエストヘッダー内

const token = req.headers.authorization;

🔹 req.params ではありませんが、これも正当なパラメータです。
✔️ 認証トークンやコンテンツタイプなどの取得には req.headers を使います。

4. Cookie パラメータ

Cookie: session_id=xyz123

• パラメータ名と値：
  • session_id = xyz123
• 場所：HTTP リクエストヘッダーの Cookie フィールド内

const sessionId = req.cookies.session_id;

🔹 ヘッダー同様、Cookie もパラメータですが req.params には含まれません。
✔️ req.cookies（※cookie-parser ミドルウェアが必要）でアクセスします。

5. Body パラメータ

{
  "name": "Alice",
  "email": "alice@example.com"
}

• パラメータ名と値：
  • name = Alice
  • email = alice@example.com
• 場所：HTTP リクエストのボディ部分

const { name, email } = req.body;

🔹 POST や PUT で構造化データを送信する際によく使われます。
✔️ これらは req.params ではなく、req.body から取得します。

適切なパラメータの種類を選ぶには？

日々の開発において、パラメータを正しく使い分けることで、ドキュメントが明確になるだけでなく、デバッグ効率も上がり、フロントエンドとバックエンドの連携が格段にスムーズになります。以下のガイドラインは、すべての API 開発者にとって有益です：

Path パラメータ：リソースを一意に識別するために使う

推奨：値がリソースを一意に識別する場合は、Path に置くべきです。迷う必要はありません。

🔹 EchoAPI では RESTful パスを自動的に認識し、{id} のように書くだけでOKです。

Query パラメータ：振る舞いを制御するために使う

推奨：フィルタリング、ページネーション、検索機能などでは Query パラメータを優先しましょう。

🔹 EchoAPI では Query パラメータをビジュアルに設定でき、サンプル値や説明文の入力、グローバルパラメータの再利用が可能です。

Header パラメータ：リクエストのコンテキストを伝える

推奨：トークン、言語設定、フォーマット指定などは Header に置くべきです。URL に詰め込まないようにしましょう。

🔹 EchoAPI では、よく使うヘッダーをドロップダウンから簡単に設定できます。

Body パラメータ：実際のデータを送信する

推奨：構造化データ、フォーム、ファイルアップロードなどでは、必ず Body を使いましょう。

🔹 EchoAPI は JSON、form-data、urlencoded、raw、binary、msgpack、XML など多数の形式に対応し、Schema 連携で自動的に構造を生成できます。

Cookie パラメータ：古典的だが、今でも有効

推奨：主にセッション管理やトラッキングに使われます。フロントエンド・バックエンド分離型の設計ではなるべく避け、パブリック API では Token の使用を推奨します。

🔹 EchoAPI は Cookie の設定もサポートしており、テスト時のブラウザ動作の再現に役立ちます。

パラメータには種類と場所の違いがありますが、それらはすべて API との会話の手段です。適切な場所に置くことで、API はより明確で使いやすくなります。

もしこの記事がパラメータの整理に役立ったなら、ぜひチームにも共有してください。
もう「この ID は Path？Query？」なんて迷わなくて大丈夫。

今日から、API 設計はロジックとルールで！

EchoAPI：API 設計の効率を最大化する体験

設計は単なるドキュメントではなく、未来のための設計図です。設計があってこそ、コラボ・再利用・テストがしやすくなります。

• 設計ビューでは、状態、タグ、パラメータ、レスポンス構造を定義でき、Schema からモック例や期待レスポンスを自動生成できます。
• 一度設計すれば、EchoAPI はすぐにデバッグ用エンドポイントと Mock サービスを生成。 フロントエンドや QA チームは、バックエンドの実装を待たずに統合を開始できます。
• 多様な認証方式をサポート：Bearer、Basic、OAuth1、AWS、NTLM、そして Akamai EdgeGrid にまで対応！

将来の自分のためのクイックリファレンス

そして最後にもうひとつ：

EchoAPI は設計・ドキュメント・デバッグ・モックの全工程を一貫してサポート。
AI によるインターフェース自動生成もあり、完全無料で試用可能。さまざまな開発環境とシームレスに統合できます。

コードは最小限に、ビジネスロジックは最大限に。