クエリパラメータとパスパラメータの使い分け

URL 設計でどちらを使うか迷ったとき、判断の軸は「そのパラメータがリソースを特定するものか、処理の条件を指定するものか」です。

パスパラメータとクエリパラメータの概要

パスパラメータは URL のパス部分に埋め込む値です。/users/42 の 42 がその例で、「どのリソースか」を示します。省略すると別のエンドポイントを指してしまうため、必須の情報を置く形になります。

クエリパラメータは ? 以降に key=value 形式で続けます。/articles?sort=new&page=2 のように、同じリソース群への絞り込みや並び替えなど、条件を付加する用途に使います。省略しても URL 自体は成立します。

2つの違い

使い分けの判断基準

「そのパラメータがなければリソースを特定できないか」で切り分けます。ユーザー ID や記事 ID など、値が変われば別のリソースを指すものはパスパラメータが自然です。一方、検索キーワードやソート順・フィルタ条件のように、なくても同じリソース集合にアクセスできるものはクエリパラメータに置きます¹。

# パスパラメータ: 特定の記事を取得
GET /articles/99

# クエリパラメータ: 記事一覧を絞り込む
GET /articles?author=alice&sort=created_at

具体的なシナリオ

EC サイトの商品ページを設計するとします。/products/sku-1234 はパスパラメータで特定の商品を指します。そのページに「カラー」「サイズ」の在庫フィルタを付けるなら /products/sku-1234?color=red&size=M とクエリパラメータで表現します。

もし商品 ID もクエリパラメータで /products?id=sku-1234 と書いた場合、/products というエンドポイントが「商品の一覧」なのか「単一商品の取得」なのか URL を見ただけでは分かりにくくなります。パスにリソース特定の情報を置くことで、エンドポイントの意味が明確になります。

パスパラメータで渡す値にスラッシュを含む場合、フレームワーク側のルーティングがパスを分割してしまうことがあります。その場合はエンコード（%2F）か、設計を見直すかを検討してください。

早見表

次に気になるのが「同じ ID をパスとクエリの両方から受け取れる実装にしてよいか」という問題です。技術的には可能ですが、REST API として公開する場合は一方に統一しないと、クライアント実装やドキュメントが混乱します。エンドポイントごとにどちらかに決め切るのが無難です。