ADP
API Design PrincipleBETA

English

繁體中文

English

繁體中文

Appearance

[ADP-356] Batch Request ​

Guidance ​

  • SHOULD choose between two common ways to implement batch requests/responses:

    • Use multipart/mixed
    • Have a batch action with HTTP POST

  • MUST support the execution of multiple operations in a single HTTP request to improve efficiency and reduce network overhead.

  • MUST maintain the same level of validation and error handling for each individual operation within the batch as if they were executed separately.

  • MAY include different types of operations (e.g., GET, POST, PUT, DELETE) within a single batch request.

  • MUST limit the number of operations per batch to prevent server overload and ensure manageable request sizes.

  • SHOULD support both synchronous and asynchronous processing of batch requests.

  • MUST include metadata about the batch request to enable clients to understand the context and status of the operations.

Batch Request (HTTP multipart/mixed) ​

  • MUST use the multipart/mixed content type for the request body.
  • MUST include each individual operation as a separate part within the multipart body.
  • MUST specify the HTTP method, URL, and any necessary headers for each operation within its part.

Batch Request (POST /resource/batch) ​

  • MUST use a JSON array to represent multiple operations in the request body.
  • MUST include the HTTP method, URL, and any necessary headers and body for each operation within the array.

Batch Response ​

  • MUST return a single HTTP response containing the results of all operations included in the batch request.
  • MUST include individual status codes and headers/body for each operation to provide detailed feedback on the success or failure of each.
  • MUST maintain the order of operations in the response to match the order of operations in the request.
  • MUST include error details for any failed operations to assist in troubleshooting and resolution.
  • MUST NOT fail the entire batch if one of the requests fails.
  • MUST return an appropriate status code for the overall batch request.

Examples ​

Batch Request Example (HTTP multipart/mixed) ​

http
POST /batch HTTP/1.1
Content-Type: multipart/mixed; boundary=batch_boundary

--batch_boundary
Content-Type: application/http
Content-Transfer-Encoding: binary

POST /resources HTTP/1.1
Content-Type: application/json

{
  "name": "Resource 1",
  "type": "Type A"
}
--batch_boundary
Content-Type: application/http
Content-Transfer-Encoding: binary

PUT /resources/123 HTTP/1.1
Content-Type: application/json

{
  "name": "Updated Resource"
}
--batch_boundary
Content-Type: application/http
Content-Transfer-Encoding: binary

DELETE /resources/456 HTTP/1.1
--batch_boundary--

Batch Response Example (HTTP multipart/mixed) ​

http
HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary=batch_boundary

--batch_boundary
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "789",
  "name": "Resource 1",
  "type": "Type A"
}
--batch_boundary
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "123",
  "name": "Updated Resource"
}
--batch_boundary
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 204 No Content
--batch_boundary--

Batch Request Example (POST /resource/batch) ​

http
POST /batch HTTP/1.1
Content-Type: application/json

{
  "batch": [
    {
      "method": "POST",
      "url": "/resources",
      "body": {
        "name": "Resource 1",
        "type": "Type A"
      }
    },
    {
      "method": "PUT",
      "url": "/resources/123",
      "body": {
        "name": "Updated Resource"
      }
    },
    {
      "method": "DELETE",
      "url": "/resources/456"
    }
  ]
}

Batch Response Example (POST /resource/batch) ​

http
HTTP/1.1 200 OK

{
  "batch": [
    {
      "status": 201,
      "body": {
        "id": "789",
        "name": "Resource 1",
        "type": "Type A"
      }
    },
    {
      "status": 200,
      "body": {
        "id": "123",
        "name": "Updated Resource"
      }
    },
    {
      "status": 204,
      "body": null
    }
  ]
}

OpenAPI 3.1.0 Example ​

yaml
openapi: 3.1.0
paths:
  /batch:
    post:
      summary: Execute a batch of operations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/BatchOperation'
      responses:
        '200':
          description: Successful batch response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BatchOperationResponse'
components:
  schemas:
    BatchOperation:
      type: object
      properties:
        method:
          type: string
        url:
          type: string
        body:
          type: object
    BatchOperationResponse:
      type: object
      properties:
        status:
          type: integer
        body:
          type: object

Reference ​

Design References ​

Changelog ​

  • 2024.09.24 Remove unwanted /api path in the samples