REST
What
REST は規格ではなく書き方の流儀。
URL は資源（名詞）だけを書き、何をするか（動詞）は HTTP メソッドで表す。
なぜ動詞を URL に書かないのか
① 学習コストが毎回リセットされる。
動詞の名前は API ごとに自由なので、同じ削除でも A社は POST /deleteUser、B社は GET /user/remove?id=42 になる。他社で身につけた感覚が使い回せない。
② 「GET は安全」という HTTP の約束が壊れる。
HTTP は「GET は何度呼んでもデータを壊さない」前提で動いている。GET /deleteUser?id=42 を作ると、先読みされただけでデータが消える。
How：棚と1冊で意味が変わる
| メソッド | /users（棚） | /users/42（1冊） |
|---|---|---|
| GET | 一覧を取得 | その1件を取得 |
| POST | 新しく1件つくる（→ 201 Created） | 使わない（id がまだ無い） |
| PUT / PATCH | 使わない（棚ごと総入れ替えは危険） | その1件を更新（PUT＝丸ごと / PATCH＝一部） |
| DELETE | 使わない（全消しは事故） | その1件を削除（→ 204 No Content） |
パスは「誰に対して」、メソッドは「何をしろ」。セットで読む。
How：エンドポイントを分解して読む
GET /repos/{owner}/{repo}/issues?state=open&per_page=30
- メソッド（
GET）＝どうする - パスパラメータ（
{owner}{repo}）＝どの資源の話か。変えると別のモノを指す - サブ資源（
/issues）＝資源の中の資源。左から入れ子で読む - クエリパラメータ（
?以降）＝どう見せてほしいか。指すモノは同じ、見せ方が変わるだけ
ただしこの流儀を守っていない API も普通にある（POST /api/v2/item.search のような形）。
関連
- API — API まわりの地図
- HTTPリクエストの構造 — 4点セット。この章の土台
Table of contents