ADP
API Design PrincipleBETA

繁體中文

English

繁體中文

English

Appearance

[ADP-760] OpenAPI: Webhooks ​

指導原則 ​

  • 必須(MUST)使用 OpenAPI 3.1.0 或更高版本來定義 webhooks
  • 必須(MUST)使用 OpenAPI 文件中的 webhooks 部分來定義 webhooks
  • 應(SHOULD)為每個 webhook 提供清晰的描述，包括其目的和觸發時機
  • 應(SHOULD)定義每個 webhook 的預期負載結構
  • 應(SHOULD)指定 webhook 端點的任何身份驗證要求
  • 應(SHOULD)包含每個 webhook 的示例負載
  • 應(SHOULD)使用適當的 HTTP 狀態碼作為 webhook 回應
  • 可(MAY)包含 webhooks 的速率限制資訊

示例 ​

yaml
openapi: 3.1.0
info:
  title: Webhook 示例
  version: 1.0.0

webhooks:
  newPet:
    post:
      summary: 關於新寵物的資訊
      description: 當系統添加新寵物時觸發的 webhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewPetPayload'
      responses:
        '200':
          description: Webhook 成功接收
        '401':
          description: 未經授權
        '429':
          description: 請求過多

components:
  schemas:
    NewPetPayload:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          description: 寵物的唯一標識符
        name:
          type: string
          description: 給寵物起的名字
        tag:
          type: string
          description: 分配給寵物的標籤

  securitySchemes:
    webhookAuth:
      type: http
      scheme: bearer

相關 ADPs ​

  • [ADP-601] API 設計中的事件
  • [ADP-607] 事件追蹤
  • [ADP-42] API 生命週期管理

參考資料 ​