API Designer

API デザイナー

堅牢で、スケーラブルで、開発者にとって使いやすい API を設計します。

コア原則

1. 開発者体験を最優先

• 明確で予測しやすい命名規則
• 包括的なドキュメント
• 役立つエラーメッセージ
• エンドポイント全体で一貫したパターン

2. 進化を前提に設計

• 初日からのバージョニング戦略
• 後方互換性
• 非推奨化のプロセス
• 破壊的変更に対する移行ガイド

3. デフォルトでセキュリティを確保

• 認証と認可
• レート制限とスロットリング
• 入力の検証とサニタイズ
• 例外なく HTTPS のみを使用

4. パフォーマンスを重視

• 効率的なクエリとインデックス作成
• キャッシュ戦略
• 大規模データセット向けのページネーション
• 圧縮（gzip、brotli）

REST API 設計

リソースの命名規則

✅ Good (Nouns, plural, hierarchical):
GET    /users                  # List all users
GET    /users/123              # Get specific user
POST   /users                  # Create user
PUT    /users/123              # Replace user
PATCH  /users/123              # Update user
DELETE /users/123              # Delete user
GET    /users/123/posts        # User's posts (nested)
GET    /users/123/posts/456    # Specific post

❌ Bad (Verbs, inconsistent, unclear):
GET /getUsers
POST /createUser
GET /user-list
GET /UserData?id=123

HTTP メソッドとセマンティクス

メソッド	目的	冪等性	安全性	リクエストボディ	レスポンスボディ
GET	データを取得	はい	はい	いいえ	はい
POST	リソースを作成	いいえ	いいえ	はい	はい（作成済み）
PUT	リソースを置換	はい	いいえ	はい	はい（任意）
PATCH	部分的に更新	いいえ	いいえ	はい	はい（任意）
DELETE	リソースを削除	はい	いいえ	いいえ	いいえ（204）または はい

冪等性：同一のリクエストを複数回送信しても、1 回送信した場合と同じ効果になります。 安全性：リクエストによってサーバーの状態は変更されません。

HTTP ステータスコード

成功（2xx）：

• 200 OK - GET、PUT、PATCH、DELETE の成功
• 201 Created - POST の成功。Location ヘッダーを含みます
• 204 No Content - リクエストの成功。レスポンスボディはありません（DELETE でよく使用されます）

クライアントエラー（4xx）：

• 400 Bad Request - 構文が無効、または検証エラー
• 401 Unauthorized - 認証が必要、または認証に失敗
• 403 Forbidden - 認証済みですが、権限がありません
• 404 Not Found - リソースが存在しません
• 409 Conflict - リクエストが現在の状態と競合しています
• 422 Unprocessable Entity - 検証エラー（意味的なエラー）
• 429 Too Many Requests - レート制限を超過しました

サーバーエラー（5xx）：

• 500 Internal Server Error - 一般的なサーバーエラー
• 502 Bad Gateway - 上流サービスのエラー
• 503 Service Unavailable - 一時的に利用できません
• 504 Gateway Timeout - 上流のタイムアウト

レスポンス形式の標準

成功レスポンス：

{
  "data": {
    "id": "123",
    "type": "user",
    "attributes": {
      "name": "John Doe",
      "email": "[email protected]",
      "created_at": "2025-01-15T10:30:00Z"
    }
  }
}

エラーレスポンス：

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "code": "REQUIRED",
        "message": "Email is required"
      },
      {
        "field": "age",
        "code": "OUT_OF_RANGE",
        "message": "Age must be between 18 and 120"
      }
    ],
    "request_id": "req_abc123",
    "documentation_url": "https://api.example.com/docs/errors/validation"
  }
}

ページネーション付きリストレスポンス：

{
  "data": [...],
  "pagination": {
    "cursor": "eyJpZCI6MTIzfQ==",
    "has_more": true,
    "total_count": 1000
  },
  "links": {
    "next": "/users?cursor=eyJpZCI6MTIzfQ==&limit=20",
    "prev": "/users?cursor=eyJpZCI6MTAwfQ==&limit=20"
  }
}

ページネーション戦略

カーソルベース（推奨）：

GET /users?cursor=abc123&limit=20

Pros: Consistent results, efficient, handles real-time data
Cons: Can't jump to arbitrary page
Use when: Large datasets, real-time data, performance critical

オフセットベース：

GET /users?page=1&per_page=20
GET /users?offset=0&limit=20

Pros: Simple, can jump to any page
Cons: Inconsistent with concurrent writes, inefficient at scale
Use when: Small datasets, admin interfaces, simple use cases

フィルタリング、ソート、検索

フィルタリング：

GET /users?status=active&role=admin&created_after=2025-01-01

ソート：

GET /users?sort=-created_at,name  # Descending created_at, then ascending name

検索：

GET /users?q=john&fields=name,email  # Search across specified fields

認証と認可

JWT ベアラートークン（SPA に推奨）：

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Pros: Stateless, includes user claims, works across domains
Cons: Can't revoke until expiry, larger payload

API キー（サービス間通信向け）：

X-API-Key: sk_live_abc123...

Pros: Simple, easy to rotate, per-service keys
Cons: No user context, must be kept secret

OAuth 2.0（サードパーティアクセス向け）：

Authorization: Bearer access_token

Pros: Delegated auth, scoped permissions, industry standard
Cons: Complex setup, requires OAuth server

Basic 認証（内部ツール／管理ツール専用）：

Authorization: Basic base64(username:password)

Pros: Simple, built-in to HTTP
Cons: Credentials in every request, must use HTTPS

レート制限

標準ヘッダー：

X-RateLimit-Limit: 1000          # Max requests per window
X-RateLimit-Remaining: 999       # Requests left
X-RateLimit-Reset: 1640995200    # Unix timestamp when limit resets
Retry-After: 60                  # Seconds to wait (on 429)

一般的な戦略：

• 固定ウィンドウ：1 時間あたり 1000 リクエスト
• スライディングウィンドウ：ローリング 1 時間あたり 1000 リクエスト
• トークンバケット：補充率に応じたバースト許容量
• ユーザー別、IP 別、または API キー別の制限

バージョニング戦略

URL バージョニング（推奨）：

/v1/users
/v2/users

Pros: Explicit, easy to route, clear in logs
Cons: URL pollution, harder to evolve incrementally

ヘッダーバージョニング：

Accept: application/vnd.myapp.v2+json
API-Version: 2

Pros: Clean URLs, follows REST principles
Cons: Less visible, harder to test in browser

ベストプラクティス：

• v0 ではなく v1 から始めます
• 破壊的変更がある場合にのみバージョンを上げます
• N と N-1 のバージョンを同時にサポートします
• 移行ガイドを提供します
• 6～12 か月前に非推奨化を告知します

---

GraphQL API 設計

スキーマ設計

type User {
  id: ID!
  name: String!
  email: String!
  posts(first: Int, after: String): PostConnection!
  createdAt: DateTime!
}

type PostConnection {
  edges: [PostEdge!]!
  pageInfo: PageInfo!
}

type PostEdge {
  node: Post!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  endCursor: String
}

type Query {
  user(id: ID!): User
  users(first: Int, after: String): UserConnection!
}

type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
  updateUser(id: ID!, input: UpdateUserInput!): UpdateUserPayload!
}

input CreateUserInput {
  name: String!
  email: String!
}

type CreateUserPayload {
  user: User
  errors: [Error!]
}

GraphQL のベストプラクティス

1. ページネーションには Relay Connection パターンを使用する：

query {
  users(first: 10, after: "cursor") {
    edges {
      node {
        id
        name
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

2. ミューテーションには入力型を使用する：

# ✅ Good: Input type + payload
mutation {
  createUser(input: { name: "John", email: "[email protected]" }) {
    user {
      id
      name
    }
    errors {
      field
      message
    }
  }
}

# ❌ Bad: Flat arguments
mutation {
  createUser(name: "John", email: "[email protected]") {
    id
    name
  }
}

3. エラー処理：

type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
}

type CreateUserPayload {
  user: User # Null if errors
  errors: [Error!] # Field-level errors
}

type Error {
  field: String!
  code: String!
  message: String!
}

REST と GraphQL の選択

REST を使う場合：

• シンプルな CRUD 操作
• キャッシュが重要（HTTP キャッシュ）
• サードパーティ向けのパブリック API
• ファイルのアップロード／ダウンロード
• チームに GraphQL の知識がない

GraphQL を使う場合：

• クライアントに柔軟なクエリが必要
• 過剰なデータ取得／データ取得の不足を削減したい
• フロントエンドで迅速に反復開発する
• 複雑な入れ子構造のデータ関係
• 強い型付けとスキーマのメリットを活用したい

---

API ドキュメント

OpenAPI／Swagger 仕様

openapi: 3.0.0
info:
  title: User Management API
  version: 1.0.0
  description: API for managing users and posts
servers:
  - url: https://api.example.com/v1
paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      summary: Create user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserInput'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

ドキュメント作成のベストプラクティス

• ✅ リクエスト／レスポンスの例を含める
• ✅ すべてのエラーコードを文書化する
• ✅ 認証ガイドを提供する
• ✅ インタラクティブな API プレイグラウンド（Swagger UI、GraphQL Playground）
• ✅ 複数の言語でコード例を用意する
• ✅ レート制限に関する情報を記載する
• ✅ API 更新履歴を用意する

---

セキュリティチェックリスト

• HTTPS のみを使用する（HTTP を HTTPS にリダイレクトする）
• 保護されたエンドポイントでは認証を必須にする
• 認可を確認する（ユーザーが自身のデータのみアクセスできるようにする）
• 入力を検証する（スキーマ検証、サニタイズ）
• ユーザー／IP ごとにレート制限を設定する
• CORS を設定する（許可するオリジンをホワイトリストに登録する）
• SQL インジェクションを防止する（パラメーター化クエリ）
• URL に機密データを含めない（ヘッダー／本文を使用する）
• 機密性の高い操作を監査ログに記録する
• API キーをローテーションおよび失効できるようにする

---

関連リソース

関連スキル：

• frontend-builder - フロントエンドから API を利用する場合
• deployment-advisor - API のホスティングを選択する場合
• performance-optimizer - API のパフォーマンスを調整する場合

関連パターン：

• META/DECISION-FRAMEWORK.md - REST と GraphQL の選択
• STANDARDS/architecture-patterns/api-gateway-pattern.md - API ゲートウェイのアーキテクチャ（作成時）

関連プレイブック：

• PLAYBOOKS/deploy-api.md - API のデプロイ手順（作成時）
• PLAYBOOKS/version-api.md - API のバージョニングワークフロー（作成時）