エンドポイントと REST を、平たい言葉で

エンドポイントはメニューの一品だ。特定のひとつのことを行う URL にすぎない。たとえば次のようなものだ。

• https://api.weather.com/forecast — 予報を取得する
• https://api.weather.com/cities — 利用可能な都市を一覧する

同じ厨房、違う料理。それぞれのエンドポイントがひとつの機能である。

あなたが触れる API のほとんどは、REST と呼ばれるゆるいスタイルに従っている。学術的な定義は要らない。必要なのは次の2つの考えだ。

• URL はモノを指す（「リソース」）——ユーザー、注文、予報など。
• 動詞は、それに対して何をしたいかを表す。 これらの動詞は HTTP メソッドであり、ウェブの仕組みの章に出てきたものと同じだ。
  • GET — 何かを読む（予報を取得する）。安全で、何も変えない。
  • POST — 何かを作る（注文を出す、ユーザーを登録する）。
  • PUT / PATCH — すでに存在する何かを更新する。
  • DELETE — 何かを削除する。

だから GET /orders/42 は「注文番号42を読む」を意味し、DELETE /orders/42 は「それを削除する」を意味する。同じ名詞、違う動詞、まったく違う効果だ。API ドキュメントや差分を読むとき、この2語——メソッドと URL——が、リクエストが何をするかのほとんどを教えてくれる。