REST API設計: GET /users/active と GET /users/deleted の何が問題か

問題

ジュニアエンジニアが以下のエンドポイントを設計した。

GET /users/active
GET /users/deleted

何が問題で、どう修正するか？

問題点の解説

なぜダメなのか

/users/active は「active というIDを持つユーザーリソース」と解釈されてしまう。

RESTにおいてパスパラメータはリソースの識別子を表す。 /users/99 が「IDが99のユーザー」を指すように、/users/active は「IDが"active"のユーザー」を指しているように読める。

つまり active や deleted は リソースのID ではなく リソースの状態（フィルタ条件） なので、パスに含めるのは意味が間違っている。

さらなる問題: 増殖するエンドポイント

この設計を続けると:

GET /users/active
GET /users/deleted
GET /users/suspended
GET /users/pending
GET /users/verified
GET /users/unverified

状態が増えるたびにエンドポイントが増殖する。メンテナンスが困難になる。

正しい設計

クエリパラメータでフィルタする。

GET /users?status=active
GET /users?status=deleted
GET /users?status=suspended

こうすることで: - エンドポイントは /users 1つで済む - 新しい状態が増えてもエンドポイントを追加しなくて良い - 複合条件も自然に表現できる

GET /users?status=active&role=admin
GET /users?status=active&created_after=2026-01-01

まとめ

用途	悪い例	良い例
状態でフィルタ	GET /users/active	GET /users?status=active
特定ユーザー取得	—	GET /users/99

パスパラメータ = リソースの一意な識別子
クエリパラメータ = コレクションの絞り込み・オプション