## 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...` に変換して送る。生の `&` や `=` が値に混ざると区切りと誤解される ## 関連 - [[API]] — API まわりの地図 - [[エンドポイント]] — `?` より前（メソッド＋パス）の読み方 - [[ページネーション]] — クエリパラメータの代表的な実用例 - [[リンクの原理]] — URL 全体の分解はこちら