使い分けの基本
パス型
- 「何を取得したいか」をURLの構造で表す。
- その値がなければ対象が決まらない、つまり 必須・識別子 に向く。
クエリ型
- 「どう絞り込みたいか」「どう表示したいか」を追加条件として表す。
- なくても成立する 任意条件・フィルタ・並び替え・ページング に向く。
たとえば、projects の下に week という階層が本当に存在し、週ごとのページやデータが独立した意味を持つなら自然です。
向いている例:
/users/123/projects/1-
/projects/week/1が「週1のプロジェクト一覧」という 固定のページ階層 を表す場合。
同じ /projects に対して、週・状態・ソート・ページ番号などを柔軟に変えたいならこちらが向いています。
向いている例:
/projects?week=1/projects?status=open-
/projects?sort=created_at&page=2。
メリットとデメリット
| 形式 | メリット | デメリット |
|---|---|---|
パス型 /projects/week/1
|
意味が階層として伝わりやすい、リソース指向でRESTっぽい、URLが「場所」として見やすい。 | 条件が増えると階層が深くなりやすい、複数条件の表現に不向き、同じ一覧のバリエーションを大量に表しにくい。 |
クエリ型 /projects?week=1
|
条件追加がしやすい、複数フィルタを組み合わせやすい、ページングやソートと相性が良い。 | URLの意味が「検索条件」に寄るので、リソースの階層性は弱い、必須識別子には少し不向き。 |
実務での判断基準
パスに入れるべきもの
- リソースのID。
- URLだけで対象が一意に決まるもの。
- 親子関係が強く、階層として表したいもの。
クエリに入れるべきもの
- 任意の絞り込み条件。
- ソート、ページ番号、表示件数。
- 同じページの表示状態を変えるだけの値。
迷ったときの基準
- その値がなくても一覧は出せる → クエリ型。
- その値がないと対象が決まらない → パス型。
- 条件が増える可能性が高い → クエリ型。