クエリパラメータ
What — ? から後ろに付ける「見せ方の注文」
クエリパラメータは、URL の ? より後ろに key=value の形で付ける追加の指定。パスが「どの資源か」を指すのに対し、クエリは同じ資源に対する絞り込み・並び替え・件数を注文する。
?から注文が始まり、複数は&でつなぐ（?state=closed&per_page=10）- 順序は自由。あっても無くても指している資源は同じ
| パスパラメータ | クエリパラメータ | |
|---|---|---|
| 位置 | ? より前（/repos/golang/go） | ? より後（state=closed） |
| 役割 | どの資源か | その資源をどう見せるか |
| 省略 | できない | できる（既定値になる） |
判定基準は「値を変えると別のモノを指すか」。別のモノならパス、見え方が変わるだけならクエリ。どちらに入れるかは API 提供側が決めており、利用者に選択権はない。
How — GitHub の Issue 一覧で読む
GET https://api.github.com/repos/golang/go/issues?state=closed&per_page=10
「golang/go の Issue 一覧（パス）を、クローズ済みだけ・10件ずつで（クエリ）」と読む。よく出るキーは4種類。
- 絞り込み：
state=closed - 並び替え：
sort=created - 件数・ページ：
per_page=30&page=2（ページネーションの正体） - 検索語：
q=golang
使えるキーはエンドポイントごとにドキュメントの Parameters 欄が決めている。自分で発明はできない。
落とし穴
- キーを打ち間違えてもエラーにならない。typo のキー（
stete=closed）は黙って無視され、絞られていない全件が返る。「なぜか結果が多い」ときはキーの綴りを疑う - 値に日本語・スペース・記号を入れるときは URL エンコードが要る。
q=環境構築はq=%E7%92%B0...に変換して送る。生の&や=が値に混ざると区切りと誤解される
関連
Table of contents