designing-apis

API の設計

読み込むタイミング

• トリガー：REST または GraphQL のエンドポイント、API コントラクト、バージョニング、リクエスト／レスポンス形式を設計するとき
• スキップ：API サーフェスのない内部専用コードの場合

API 設計ワークフロー

このチェックリストをコピーして、進捗を記録してください。

API Design Progress:
- [ ] Step 1: Define resources and relationships
- [ ] Step 2: Design endpoint structure
- [ ] Step 3: Define request/response formats
- [ ] Step 4: Plan error handling
- [ ] Step 5: Add authentication/authorization
- [ ] Step 6: Document with OpenAPI spec
- [ ] Step 7: Validate design against checklist

REST API の設計

URL 構造

# Resource-based URLs (nouns, not verbs)
GET    /users              # List users
GET    /users/:id          # Get user
POST   /users              # Create user
PUT    /users/:id          # Replace user
PATCH  /users/:id          # Update user
DELETE /users/:id          # Delete user

# Nested resources
GET    /users/:id/orders   # User's orders
POST   /users/:id/orders   # Create order for user

# Query parameters for filtering/pagination
GET    /users?role=admin&status=active
GET    /users?page=2&limit=20&sort=-createdAt

HTTP ステータスコード

コード	意味	使用例
200	OK	GET、PUT、PATCH の成功
201	作成済み	POST の成功
204	コンテンツなし	DELETE の成功
400	不正なリクエスト	入力が無効
401	認証されていない	認証情報がない／無効
403	禁止	認証は有効だが、権限がない
404	見つからない	リソースが存在しない
409	競合	重複、状態の競合
422	処理できない	検証に失敗
429	リクエストが多すぎる	レート制限
500	内部エラー	サーバーエラー

レスポンス形式

成功レスポンス：

{
  "data": {
    "id": "123",
    "type": "user",
    "attributes": {
      "name": "John Doe",
      "email": "[email protected]"
    }
  },
  "meta": {
    "requestId": "abc-123"
  }
}

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

{
  "data": [...],
  "meta": {
    "total": 100,
    "page": 1,
    "limit": 20,
    "totalPages": 5
  },
  "links": {
    "self": "/users?page=1",
    "next": "/users?page=2",
    "last": "/users?page=5"
  }
}

エラーレスポンス：

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address"
      }
    ]
  },
  "meta": {
    "requestId": "abc-123"
  }
}

API のバージョニング

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

/api/v1/users
/api/v2/users

ヘッダーによるバージョニング：

Accept: application/vnd.example.v1+json

認証パターン

JWT ベアラートークン：

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

API キー：

X-API-Key: your-api-key

レート制限ヘッダー

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1609459200
Retry-After: 60

GraphQL パターン

スキーマ設計：

# Abbreviated: input, connection and error types omitted for brevity
type Query {
  user(id: ID!): User
  users(filter: UserFilter, pagination: Pagination): UserConnection!
}

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

type User {
  id: ID!
  name: String!
  email: String!
  orders(first: Int, after: String): OrderConnection!
}

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

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

OpenAPI 仕様テンプレート

OpenAPI 3.0 仕様テンプレートの全文は、OPENAPI-TEMPLATE.md を参照してください。

API 設計の検証

設計を完了したら、次のチェックリストに照らして検証してください。

Validation Checklist:
- [ ] All endpoints use nouns, not verbs
- [ ] HTTP methods match operations correctly
- [ ] Consistent response format across endpoints
- [ ] Error responses include actionable details
- [ ] Pagination implemented for list endpoints
- [ ] Authentication defined for protected endpoints
- [ ] Rate limiting headers documented
- [ ] OpenAPI spec is complete and valid

検証に失敗した場合は、該当する設計手順に戻って問題に対処してください。

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

• HTTPS のみ
• すべてのエンドポイントで認証
• 認可チェック
• 入力の検証
• レート制限
• リクエストサイズの制限
• CORS の適切な設定
• URL に機密データを含めない
• 監査ログ