この記事の要点

REST (Representational State Transfer) は Roy Fielding が 2000 年に提唱した分散システムのアーキテクチャスタイル リソース指向: URL は名詞 (/users/1)、動作は HTTP メソッド (GET/POST/PUT/DELETE/PATCH) CRUD と HTTP の対応: Create=POST / Read=GET / Update=PUT/PATCH / Delete=DELETE Statelessness (ステートレス): 各リクエストは完結。サーバ側にセッション状態を持たない Richardson Maturity Model: Level 0 (RPC) → 1 (リソース) → 2 (HTTP メソッド) → 3 (HATEOAS) の成熟度 OpenAPI / Swagger で仕様文書化、GraphQL / gRPC と適材適所で使い分け

REST の起源

REST はRoy Fielding が 2000 年の博士論文「Architectural Styles and the Design of Network-based Software Architectures」で提唱したアーキテクチャスタイルです。HTTP プロトコルの共著者でもある Fielding は、Web そのものが持つ性質を分散システムの設計原則として体系化しました。

REST の 6 制約

制約	内容
① クライアント・サーバ	関心の分離。UI とデータ層を独立して進化させられる
② ステートレス	サーバはセッション状態を保持しない。各リクエストが自己完結
③ キャッシュ可能	レスポンスにキャッシュ可否を明示。HTTP のキャッシュ機構を活用
④ 統一インターフェース	リソース URI / 標準 HTTP メソッド / 表現 (JSON 等) / HATEOAS
⑤ 階層化システム	プロキシ / ロードバランサ / ゲートウェイを途中に挟める
⑥ コードオンデマンド (任意)	サーバが実行可能コードをクライアントへ送れる (JavaScript)

リソース指向: URL の設計

URL は名詞でリソースを表します。動詞は HTTP メソッドが担当します:

操作	URL	HTTP メソッド
ユーザー一覧取得	/users	GET
ユーザー詳細	/users/123	GET
ユーザー作成	/users	POST
ユーザー全更新	/users/123	PUT
ユーザー部分更新	/users/123	PATCH
ユーザー削除	/users/123	DELETE
ユーザー記事一覧	/users/123/articles	GET
記事の検索	/articles?tag=php&page=2	GET

命名のアンチパターン

❌ /getUser?id=1            (動詞が URL に)
❌ /user/delete/1           (動詞が URL に)
❌ /listAllArticles          (動詞が URL に)
❌ /api/v1/userInfo          (キャメルケース)

✅ GET    /users/1
✅ DELETE /users/1
✅ GET    /articles
✅ GET    /api/v1/users/1    (kebab or snake)

HTTP ステータスコードの設計

範囲	意味	主要例
2xx 成功	処理が正常完了	200 OK / 201 Created / 204 No Content
3xx リダイレクト	別の URL を見てほしい	301 / 302 / 304 Not Modified
4xx クライアントエラー	リクエストが不正	400 / 401 / 403 / 404 / 409 / 422 / 429
5xx サーバエラー	サーバ側の問題	500 / 502 / 503 / 504

コード	意味	典型用途
200 OK	成功	GET / PUT / PATCH の成功
201 Created	作成成功	POST で新規作成時、Location ヘッダーに新リソース URL
204 No Content	成功 (本文なし)	DELETE 成功時
400 Bad Request	不正なリクエスト	JSON パース失敗、必須欠落
401 Unauthorized	未認証	トークン無し / 期限切れ
403 Forbidden	権限なし	認証はOKだが操作権限なし
404 Not Found	リソース無し	該当 ID のレコード無し
409 Conflict	衝突	楽観ロック失敗、重複登録
422 Unprocessable	バリデーションエラー	形式は OK だが値が不正
429 Too Many Requests	レート超過	Retry-After ヘッダー付与
500 Internal Server Error	サーバエラー	例外発生
503 Service Unavailable	過負荷 / メンテ	Retry-After ヘッダー付与

リクエスト / レスポンス例

# 作成
POST /api/v1/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer eyJhbGc...

{
  "name": "Alice",
  "email": "alice@example.com"
}

# 応答
HTTP/1.1 201 Created
Location: /api/v1/users/42
Content-Type: application/json

{
  "id": 42,
  "name": "Alice",
  "email": "alice@example.com",
  "created_at": "2026-06-10T10:00:00Z"
}

# 部分更新
PATCH /api/v1/users/42 HTTP/1.1
Content-Type: application/json

{ "name": "Alice Wonderland" }

# 応答
HTTP/1.1 200 OK
Content-Type: application/json

{ "id": 42, "name": "Alice Wonderland", ... }

# 削除
DELETE /api/v1/users/42 HTTP/1.1

# 応答
HTTP/1.1 204 No Content

HATEOAS とリンク

HATEOAS (Hypermedia As The Engine Of Application State) は、レスポンスに次に実行可能な操作のリンクを含めることで、クライアントが API の構造を事前に知らなくても操作を辿れる設計です。

{
  "id": 42,
  "name": "Alice",
  "_links": {
    "self":   { "href": "/api/v1/users/42" },
    "edit":   { "href": "/api/v1/users/42", "method": "PATCH" },
    "delete": { "href": "/api/v1/users/42", "method": "DELETE" },
    "articles": { "href": "/api/v1/users/42/articles" }
  }
}

Richardson Maturity Model

Level	状態	説明
0	RPC over HTTP	1 つの URL に POST するだけ (SOAP, XML-RPC)
1	リソース概念導入	URL がリソースを表す。メソッドは POST のみ
2	HTTP メソッド活用	GET/POST/PUT/DELETE を使い分け。ほとんどの「REST API」がここ
3	HATEOAS	レスポンスがリンクを含む、自己記述的

実務では Level 2 が現実解、HAL / JSON:API / Siren 等の仕様で Level 3 を狙うこともあります。

バージョニング

方式	例	賛否
URL パス	/api/v1/users	★ 一番分かりやすい
カスタムヘッダー	API-Version: 1	URL がきれい、デバッグしづらい
Accept ヘッダー	Accept: application/vnd.api+json; version=1	純粋だがクライアント実装が複雑
クエリ	/users?v=1	非推奨

OpenAPI / Swagger

REST API を YAML / JSON で記述する業界標準。仕様 → クライアント SDK 自動生成、ドキュメント自動表示 (Swagger UI) が可能。

openapi: 3.0.3
info:
  title: Sample API
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: ユーザー取得
      parameters:
        - in: path
          name: id
          required: true
          schema: { type: integer }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "404":
          description: Not Found
components:
  schemas:
    User:
      type: object
      properties:
        id: { type: integer }
        name: { type: string }
        email: { type: string, format: email }

SOAP / GraphQL / gRPC との比較

方式	強み	弱み	適
REST	シンプル、HTTP 標準、キャッシュ可能	取り過ぎ/取り足りない、複数リソース呼び出し	公開 API、CRUD、Web
SOAP	厳密な契約、WS-Security	XML 重量、複雑	金融・行政の既存システム
GraphQL	クライアント主導、必要分だけ取得	キャッシュ難、N+1 注意	モバイル、複雑な UI、BFF
gRPC	高速 (HTTP/2 + Protobuf)、ストリーミング	ブラウザ直は不可 (grpc-web 必要)	マイクロサービス間通信

エラーレスポンスの設計

RFC 7807 Problem Details for HTTP APIs が標準化された推奨形式:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json

{
  "type": "https://example.com/errors/validation",
  "title": "Validation Failed",
  "status": 422,
  "detail": "email is required",
  "instance": "/api/v1/users",
  "errors": [
    { "field": "email", "code": "required" },
    { "field": "password", "code": "too_short", "min": 8 }
  ]
}

FAQ

Q: PUT と PATCH の違いは？
A: PUT はリソース全体の置換、PATCH は部分更新。PUT で送らなかった項目は null 化される設計が原則。

Q: GET でデータ変更してよい？
A: 絶対 NG。GET はセーフ (副作用なし) + 冪等が原則。ブラウザ・プロキシがキャッシュしたり再リクエストする。

Q: REST より GraphQL の方が新しい？
A: 用途が違います。GraphQL はクライアントが必要な項目を選んで取得するのが強み。REST はキャッシュやシンプルさで優位。両方使う場合も多い。