OpenAPI: Batch/Bulk Operations Endpoint

Q: OpenAPI: Batch/Bulk Operations Endpoint

## Documenting Batch Operations in OpenAPI Batch endpoints let clients create, update, or delete multiple resources in a single HTTP request, reducing network overhead and improving performance. ### Batch Create Endpoint yaml paths: /users/batch: post: summary: Create multiple users tags: - Users operationId: batchCreateUsers requestBody: required: true content: application/json: schema: type: object

Document batch API endpoints for creating, updating, or deleting multiple resources in a single request. Covers array request bodies, partial success responses, and error reporting.

Batch Operations

Detailed Explanation

Documenting Batch Operations in OpenAPI

Batch endpoints let clients create, update, or delete multiple resources in a single HTTP request, reducing network overhead and improving performance.

Batch Create Endpoint

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

Batch Result Schema

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

Design Decisions

Max items limit: Always set a maxItems to prevent abuse. Document the limit clearly.
Partial success: Use HTTP 200 (not 201) for batch operations since some items may fail. The response body communicates per-item status.
Idempotency: Include an idempotency key for batch operations to prevent duplicate processing on retries.
Index-based error reporting: Each result references the input array index so clients can correlate failures with specific items.

Batch Delete Pattern

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

Use Case

Implementing bulk import features, admin dashboards that manage multiple records, or client SDKs that batch API calls to reduce latency. Common in CRM systems, data migration tools, and e-commerce inventory management.

Try It — API Documentation Generator

Open full tool →