OpenAPI: バッチ/バルク操作エンドポイント

OpenAPIでのバッチ操作の文書化

バッチエンドポイントにより、クライアントは単一のHTTPリクエストで複数リソースの作成、更新、削除が可能になり、ネットワークオーバーヘッドを削減してパフォーマンスを向上させます。

バッチ作成エンドポイント

paths:
  /users/batch:
    post:
      summary: Create multiple users
      tags:
        - Users
      operationId: batchCreateUsers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - items
              properties:
                items:
                  type: array
                  items:
                    $ref: '#/components/schemas/UserInput'
                  maxItems: 100
                  description: Array of users to create (max 100)
      responses:
        '200':
          description: Batch results (may include partial failures)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResult'
        '400':
          description: Invalid request format

バッチ結果スキーマ

components:
  schemas:
    BatchResult:
      type: object
      properties:
        total:
          type: integer
          description: Total items submitted
        succeeded:
          type: integer
          description: Number of successful operations
        failed:
          type: integer
          description: Number of failed operations
        results:
          type: array
          items:
            type: object
            properties:
              index:
                type: integer
                description: Position in the input array
              status:
                type: string
                enum:
                  - success
                  - error
              id:
                type: string
                description: Created resource ID (on success)
              error:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string

設計判断

• 最大項目制限: 不正利用を防ぐため必ずmaxItemsを設定します。制限を明確に文書化します。
• 部分成功: 一部の項目が失敗する可能性があるため、バッチ操作にはHTTP 200（201ではなく）を使用します。レスポンスボディが項目ごとのステータスを伝えます。
• 冪等性: リトライ時の重複処理を防ぐため、バッチ操作に冪等性キーを含めます。
• インデックスベースのエラーレポート: 各結果は入力配列のインデックスを参照し、クライアントが失敗を特定の項目に関連付けられるようにします。

バッチ削除パターン

/users/batch:
  delete:
    requestBody:
      content:
        application/json:
          schema:
            type: object
            properties:
              ids:
                type: array
                items:
                  type: string
                maxItems: 100