ADP
API Design PrincipleBETA

繁體中文

English

繁體中文

English

Appearance

[ADP-356] 批次請求 ​

指導原則 ​

  • 應該(SHOULD)在兩種常見的批次請求/回應實現方式中選擇:

    • 使用 multipart/mixed
    • 使用 HTTP POST 的批次操作

  • 可(MAY)支持在單一 HTTP 請求中執行多個操作，以提高效率並減少網絡開銷。

  • 可(MAY)對批次中的每個單獨操作維持與單獨執行時相同的驗證和錯誤處理級別。

  • 可以(MAY)在單一批次請求中包含不同類型的操作（例如 GET、POST、PUT、DELETE）。

  • 必須(MUST)限制每個批次的操作數量，以防止伺服器過載並確保請求大小可管理。

  • 應該(SHOULD)支持批次請求的同步和異步處理。

  • 必須(MUST)包含批次請求的元數據，以使客戶端能夠理解操作的上下文和狀態。

批次請求（HTTP multipart/mixed） ​

  • 必須(MUST)使用 multipart/mixed 內容類型作為請求主體。
  • 必須(MUST)在多部分主體中將每個單獨操作作為單獨的部分包含。
  • 必須(MUST)在每個操作的部分中指定 HTTP 方法、URL 和任何必要的標頭。

批次請求（POST /resource/batch） ​

  • 必須(MUST)使用 JSON 陣列在請求主體中表示多個操作。
  • 必須(MUST)在陣列中為每個操作包含 HTTP 方法、URL 以及任何必要的標頭和主體。

批次回應 ​

  • 必須(MUST)返回包含批次請求中所有操作結果的單一 HTTP 回應。
  • 必須(MUST)為每個操作包含單獨的狀態碼和標頭/主體，以提供每個操作成功或失敗的詳細反饋。
  • 必須(MUST)在回應中保持操作的順序與請求中的操作順序一致。
  • 必須(MUST)為任何失敗的操作包含錯誤詳情，以協助故障排除和解決。
  • 必須不(MUST NOT)因其中一個請求失敗而導致整個批次失敗。
  • 必須(MUST)為整個批次請求返回適當的狀態碼。

範例 ​

批次請求範例（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": "資源 1",
  "type": "類型 A"
}
--batch_boundary
Content-Type: application/http
Content-Transfer-Encoding: binary

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

{
  "name": "更新的資源"
}
--batch_boundary
Content-Type: application/http
Content-Transfer-Encoding: binary

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

批次回應範例（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": "資源 1",
  "type": "類型 A"
}
--batch_boundary
Content-Type: application/http
Content-Transfer-Encoding: binary

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

{
  "id": "123",
  "name": "更新的資源"
}
--batch_boundary
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 204 No Content
--batch_boundary--

批次請求範例（POST /resource/batch） ​

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

{
  "batch": [
    {
      "method": "POST",
      "url": "/resources",
      "body": {
        "name": "資源 1",
        "type": "類型 A"
      }
    },
    {
      "method": "PUT",
      "url": "/resources/123",
      "body": {
        "name": "更新的資源"
      }
    },
    {
      "method": "DELETE",
      "url": "/resources/456"
    }
  ]
}

批次回應範例（POST /resource/batch） ​

http
HTTP/1.1 200 OK

{
  "batch": [
    {
      "status": 201,
      "body": {
        "id": "789",
        "name": "資源 1",
        "type": "類型 A"
      }
    },
    {
      "status": 200,
      "body": {
        "id": "123",
        "name": "更新的資源"
      }
    },
    {
      "status": 204,
      "body": null
    }
  ]
}

OpenAPI 3.1.0 範例 ​

yaml
openapi: 3.1.0
paths:
  /batch:
    post:
      summary: 執行一批操作
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/BatchOperation'
      responses:
        '200':
          description: 成功的批次回應
          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

參考資料 ​

設計參考 ​

Changelog ​

  • 2024.09.24 Remove unwanted /api path in the samples