REST API

REST APIとは

REST(Representational State Transfer)は、[[HTTP]] の仕組みを素直に活かしてAPIを設計するスタイルです。「リソース(データ)」をURLで表し、操作をHTTPメソッドで表現します。

GET    /users        ユーザー一覧を取得
GET    /users/42     ID 42 のユーザーを取得
POST   /users        ユーザーを新規作成
PUT    /users/42     ID 42 のユーザーを更新
DELETE /users/42     ID 42 のユーザーを削除

RESTが解決したのは、APIごとにバラバラだった呼び出し規約です。RESTはWebが既に使っているHTTPの語彙 — メソッド・URL・ステータスコード・ヘッダー — をそのままAPIの語彙に流用します。おかげで初めて見るAPIでも GET /products/12 の意味が推測でき、ブラウザやcurl、プロキシ、キャッシュがそのまま通用します。

RESTは厳密な仕様ではなく設計の指針です。実務の「REST API」は「HTTPの流儀に沿ったJSONのAPI」くらいの緩い意味で使われます。

用語の地図

RESTの周辺の言葉は、次の7つで見通せます。

  • リソース — 操作の対象。/users/42 のようにURLで一意に指す
  • エンドポイント — URLとメソッドの組。API1つ分の入口
  • メソッド — GET / POST / PUT / PATCH / DELETE([[HTTP]])
  • ステータスコード — 結果を3桁の数字で伝える([[HTTPステータスコード]])
  • 表現(representation) — 中身を運ぶ形式。実務ではほぼ [[JSON]]
  • ステートレス — サーバーは前のリクエストを覚えない。認証トークンなど必要な情報は毎回のリクエストに含める([[認証と認可]])
  • 冪等性 — 同じリクエストを何度送っても結果が変わらない性質([[冪等性]])

URL設計の基本

  • URLは名詞、操作はメソッド — POST /users/42/delete ではなく DELETE /users/42
  • 集合は複数形、個体はその下 — 一覧は /users、1件は /users/42
  • 階層は所属を表す — /users/42/orders は「ユーザー42の注文」
  • 絞り込みや並べ替えはクエリパラメータ — /users?role=admin&page=2

更新が2つあるのは範囲の違いで、PUTは全体の置き換え、PATCHは一部だけの更新です。

ステータスコードの基本

コード意味
200 OK成功
201 Created作成成功
400 Bad Requestリクエストが不正
401 / 403未認証 / 権限なし
404 Not Foundリソースが存在しない
500サーバー内部エラー

ここに無い3xx・409・422・502の切り分けは [[HTTPステータスコード]] へ。

REST APIから次に読む地図

土台を固める — [[HTTP]]、[[HTTPステータスコード]]、[[JSON]]。この3つでREST APIの読み書きはほぼ困りません。

設計する — 壊さず育てるのが [[APIバージョニング]]、再送で事故らせないのが [[冪等性]]、受け取ったデータの検証が [[JSON Schema]]、GETの結果の使い回しが [[HTTPキャッシュ]]。

守る — 誰の要求かを確かめる [[認証と認可]] と標準的な手順の [[OAuth・OIDC]]、状態を運ぶトークンの [[JWT]]。ブラウザから呼ぶとまず出会う [[CORS]]、流量を絞る [[レートリミット]]、入口でまとめて担う [[APIゲートウェイ]]。状態をサーバーに置く従来型との対比は [[セッション管理]]。

作って呼ぶ — サーバー実装の代表格は [[Node.js]]、ブラウザ側から呼び出す手段は [[fetchと非同期通信]]、失敗したときの再試行は [[エラーハンドリングとリトライ設計]]。

別の道具へ逃がす — 取得の過不足が辛いなら [[GraphQL]]、サービス間の速度と型の厳密さなら [[gRPC]]、サーバーからの随時プッシュなら [[WebSocket]]、逆向きの通知なら [[Webhook]]。捨てるのではなく苦手な部分だけを任せる使い分けです。

関連技術とのつながり

  • [[HTTP]] — RESTの土台となるプロトコル
  • [[JSON]] — やり取りするデータの形式
  • [[GraphQL]] — 取得の過不足に対する別アプローチ
  • [[Node.js]] — サーバー実装の代表的な環境
Q: RESTの設計の覚え方として記事で紹介されているのはどれ?
- [ ] URLが動詞、HTTPメソッドが名詞
- [x] URLが名詞、HTTPメソッドが動詞
- [ ] URLもメソッドもすべて名詞で統一する
解説: リソース(データ)をURLで表し、操作をHTTPメソッドで表現するのがRESTの基本です。

Q: ステータスコード 201 の意味は?
- [ ] リクエストが不正
- [ ] リソースが存在しない
- [x] 作成成功
- [ ] サーバー内部エラー
解説: 201 Createdは作成成功を表し、400は不正なリクエスト、404は存在しないリソースです。

Q: RESTの「ステートレス」の説明として正しいのはどれ?
- [x] サーバーはリクエスト間の状態を覚えず、毎回必要な情報をリクエストに含める
- [ ] サーバーがすべてのユーザーの状態を記憶し続ける
- [ ] 一度接続したら切断しない
解説: ステートレスではサーバーが状態を覚えないため、認証トークンなど必要な情報を毎回のリクエストに含めます。

Q: 記事が示すURL設計の指針に合うのはどれ?
- [ ] `POST /users/42/delete` のようにURLへ操作名を含める
- [x] `DELETE /users/42` のようにURLは名詞にし、操作はHTTPメソッドで表す
- [ ] すべての操作を `/api` という1本のURLに集約する
解説: URLはリソースを指す名詞にし、動詞にあたる操作はHTTPメソッドが担当します。