過去バージョン

REST の起源

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

REST の 6 制約

リソース指向: URL の設計

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

命名のアンチパターン

❌ /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 ステータスコードの設計

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

# 作成
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 2 が現実解、HAL / JSON:API / Siren 等の仕様で Level 3 を狙うこともあります。

バージョニング

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 との比較

エラーレスポンスの設計

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 はキャッシュやシンプルさで優位。両方使う場合も多い。