REST API

REST API とは

REST (Representational State Transfer) は、Roy Fielding が 2000 年の博士論文で定義した Web API のアーキテクチャスタイルである。HTTP メソッドとリソース指向の URL でデータを操作する。

HTTP メソッドと CRUD

HTTP メソッドと CRUD を以下にまとめる。

メソッド	操作	冪等	例
GET	取得	✅	GET /users/123
POST	作成	❌	POST /users
PUT	全体更新	✅	PUT /users/123
PATCH	部分更新	❌	PATCH /users/123
DELETE	削除	✅	DELETE /users/123

URL 設計

URL 設計を図で示す。

✅ リソース指向
GET    /users          ← ユーザー一覧
GET    /users/123      ← ユーザー取得
POST   /users          ← ユーザー作成
PUT    /users/123      ← ユーザー更新
DELETE /users/123      ← ユーザー削除
GET    /users/123/orders ← ユーザーの注文一覧

❌ 動詞ベース
GET /getUser?id=123
POST /createUser
POST /deleteUser

ステータスコード

ステータスコードを以下にまとめる。

コード	意味	用途
200	OK	成功
201	Created	リソース作成成功
204	No Content	削除成功
400	Bad Request	リクエストが不正
401	Unauthorized	認証が必要
403	Forbidden	権限がない
404	Not Found	リソースが存在しない
429	Too Many Requests	レート制限
500	Internal Server Error	サーバーエラー

GraphQL との比較

GraphQL との主な違いを以下に比較する。

観点	REST	GraphQL
エンドポイント	リソースごとに複数	1 つ (/graphql)
データ取得	固定レスポンス	クライアントが選択
Over-fetching	発生する	発生しない
キャッシュ	HTTP キャッシュが使える	工夫が必要
学習コスト	低い	中程度

ページネーション

ページネーションを図で示す。

GET /users?limit=20&cursor=eyJpZCI6IjEyMyJ9

{
  "items": [...],
  "nextCursor": "eyJpZCI6IjE0MyJ9"
}

カーソルベースのページネーションが DynamoDB と相性が良い。

全体像を把握するには関連書籍も有用。