はじめに
API を設計していると、こう悩むこともあるでしょう。
「この値って、URLのどこに入れるのが正解なんだっけ？」
・/users/1
・/users?id=1
どちらも動きます。
でも 意味はまったく違います。
この記事では、
クエリパラメータ
パスパラメータ
この2つの違いと正しい使い分けを
Laravel × React のコード例つきで解説 します。
今日のゴール
・パスパラメータとクエリパラメータの違いを説明できる
・検索条件・ページネーションの設計ができる
・Laravel 側で正しく受け取れる
・React 側で正しくURLを組み立てられる
まず結論：役割はまったく違う
| 種類 | 意味 | 使う場面 |
|---|---|---|
| パスパラメータ | 「どのリソースか？」 | 詳細取得・更新・削除 |
| クエリパラメータ | 「どういう条件で？」 | 検索・絞り込み・並び替え |
パスパラメータとは？（どのデータか）
例：
GET /users/1
これは
「ID が 1 のユーザー」
を取得するリクエストです。
Laravel での受け取り方
ルート定義
Route::get('/users/{id}', function ($id) {
return ['id' => $id];
});
実行結果
/api/users/10
{"id":10}
よく使う場面
| 操作 | パス |
|---|---|
| 詳細取得 | GET /users/1 |
| 更新 | PUT /users/1 |
| 削除 | DELETE /users/1 |
クエリパラメータとは？（条件指定）
例：
GET /users?role=admin&page=2
これは
権限が admin
2ページ目
という 「検索条件」 を指定しています。
Laravelでの受け取り方
Route::get('/users', function () {
$role = request()->query('role');
$page = request()->query('page');
return compact('role', 'page');
});
React 側でクエリを付ける
axios.get('/api/users', {
params: {
role: 'admin',
page: 2
}
});
実際のURL：
/api/users?role=admin&page=2
実務でよくある「正しい設計」
詳細ページ
正しい
GET /users/1
微妙
GET /users?id=1
→ 「どの1件か」はパスで表現するのがREST的。
検索・一覧
正しい
GET /users?keyword=tanaka&sort=asc&page=2
微妙
GET /searchUsers?keyword=tanaka
フィルター付き一覧
正しい
GET /posts?category=tech&likes=10
初心者が必ずハマるNGパターン
すべてをパスに詰め込む
/users/admin/2
→ 何が何だかわからなくなります。
すべてをクエリに詰め込む
/users?id=1
取得自体はできるが、
REST API としての可読性が落ちる
フロントとバックの「意味の共有」ができなくなる
ルールを一言でまとめると
リソースの特定 → パスパラメータ
条件の指定 → クエリパラメータ
このルールだけ覚えておけば、
あなたの URL 設計はもう迷いません。
実務でよく使うURLまとめ
| 目的 | URL |
|---|---|
| 一覧 | GET /users |
| 詳細 | GET /users/1 |
| 検索 | GET /users?keyword=aaa |
| 並び替え | GET /users?sort=desc |
| ページ移動 | GET /users?page=2 |
今日のまとめ
・パスパラメータ = どのデータか
・クエリパラメータ = どういう条件か
・詳細取得・更新・削除 → パス
・検索・ページネーション・絞り込み → クエリ
・このルールを守るだけでAPI設計は一気に美しくなる
次回 Day6 は…
「Cookie と Session の仕組みを理解する」
ログイン機能がなぜ成り立っているのかを
“ブラウザ目線” と “サーバ目線” の両方で解説します。