api-design-patterns

API 設計パターン

リソースの命名

• 複数形の名詞を使用します：/users、/orders、/products
• 関連性を表すには階層化します：/users/{id}/orders
• 階層の深さは最大2レベルにします。それを超える場合は、クエリパラメーターまたはトップレベルのリソースを使用します
• ケバブケースを使用します：/user-profiles。/userProfiles は使用しません
• URLに動詞を含めないでください：/users/{id}/activate は誤りです。POST /users/{id}/activation を使用します

HTTPメソッド

メソッド	用途	冪等性	リクエストボディ	成功コード
GET	リソースの読み取り	あり	なし	200
POST	リソースの作成	なし	あり	201
PUT	全体の置き換え	あり	あり	200
PATCH	部分更新	なし	あり	200
DELETE	リソースの削除	あり	なし	204

POSTでは、作成したリソースのURLをLocationヘッダーで返します。

ステータスコード

200 OK              - Successful read/update
201 Created         - Successful creation
204 No Content      - Successful delete
400 Bad Request     - Validation error (include field-level errors)
401 Unauthorized    - Missing or invalid authentication
403 Forbidden       - Authenticated but not authorized
404 Not Found       - Resource does not exist
409 Conflict        - State conflict (duplicate, version mismatch)
422 Unprocessable   - Semantically invalid (valid JSON, bad values)
429 Too Many Reqs   - Rate limited (include Retry-After header)
500 Internal Error  - Unhandled server error (never expose stack traces)

エラーレスポンスの形式

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      { "field": "email", "message": "Must be a valid email address" },
      { "field": "age", "message": "Must be at least 18" }
    ]
  }
}

API全体で一貫したエラーコードを使用します。すべてのコードをAPIリファレンスに記載してください。

カーソルベースのページネーション（推奨）

GET /users?limit=20&cursor=eyJpZCI6MTAwfQ

Response:
{
  "data": [...],
  "pagination": {
    "next_cursor": "eyJpZCI6MTIwfQ",
    "has_more": true
  }
}

大規模なデータセットや頻繁に変更されるデータセットには、カーソルページネーションを使用します。カーソルは不透明なbase64文字列としてエンコードします。カーソルに生のIDを公開しないでください。

オフセットベースのページネーション（単純なケースのみ）

GET /users?page=3&per_page=20

Response:
{
  "data": [...],
  "pagination": {
    "page": 3,
    "per_page": 20,
    "total": 245,
    "total_pages": 13
  }
}

オフセットページネーションは、合計件数の取得コストが低く、データセットが小さい場合にのみ使用します。

フィルタリングと並べ替え

GET /orders?status=pending&created_after=2025-01-01&sort=-created_at,+total
GET /products?category=electronics&price_min=100&price_max=500
GET /users?search=john&fields=id,name,email

ペイロードサイズを削減するには、フィールド選択（fieldsパラメーター）を使用します。降順にする場合は、並べ替えフィールドの先頭に-を付けます。

バージョニング

シンプルにするため、URLパスによるバージョニングを推奨します：

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

ルール：

• v1の公開後は、互換性を破壊しないでください。フィールドを削除せず、追加してください。
• 新しい必須フィールドを追加する場合は、新しいバージョンを作成します
• 古いバージョンは、Sunsetヘッダーと6か月前の通知で廃止します
• 同時にサポートするアクティブなバージョンは最大2つにします

リクエスト／レスポンスヘッダー

Content-Type: application/json
Accept: application/json
Authorization: Bearer <token>
X-Request-Id: <uuid>          # For tracing
X-RateLimit-Limit: 100        # Requests per window
X-RateLimit-Remaining: 47     # Remaining in window
X-RateLimit-Reset: 1700000000 # Window reset Unix timestamp
Retry-After: 30               # Seconds until rate limit resets

デバッグのため、レスポンスでは常にX-Request-Idを返します。

OpenAPI仕様のガイドライン

• 先に仕様を作成し、その後に実装します（仕様駆動開発）
• 共通スキーマには$refを使用します：$ref: '#/components/schemas/User'
• すべてのエンドポイントにexamplesを定義します
• 多相レスポンスにはoneOf／anyOfを使用します
• 仕様からクライアントSDKを生成し、手書きしないでください
• ミドルウェアで仕様に照らしてリクエストを検証します

paths:
  /users/{id}:
    get:
      operationId: getUser
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFound'

レート制限の戦略

• ユーザーごと、エンドポイントごとに制限を適用します
• 固定ウィンドウではなく、スライディングウィンドウアルゴリズムを使用します
• Retry-Afterヘッダーを付けて429を返します
• ヘルスチェックと認証のエンドポイントはレート制限の対象外にします
• 不正利用の検出に備えて、レート制限されたリクエストをログに記録します