[ADP-355] 帶偏好的請求

概述

Prefer 標頭是一個僅用於請求的標頭，用於向伺服器傳達客戶端偏好。它允許客戶端影響伺服器如何處理和回應他們的請求。

關於 Prefer 標頭的一般指導，請參考 ADP-136: Prefer。

優點

1. 效率: 通過允許客戶端指定其回應格式偏好，減少頻寬和處理時間。
2. 靈活性: 使客戶端能夠根據當前需求定制請求，改善整體用戶體驗。
3. 可擴展性: 允許伺服器通過只傳遞必要數據來更有效地處理請求。

自定義偏好

自定義偏好允許客戶端定義標準偏好未涵蓋的特定行為或回應格式。這些可以根據獨特的應用需求進行定制。

語法

Prefer: foo=value, bar

• 鍵應該(SHOULD)使用 kebab-case。
• 值是可選的; 如果偏好設計為有值，它應該(SHOULD)是可枚舉的。

示例

Prefer: handling=strict, timezone=Asia/Taipei

注意:沒有基於時區請求的標準標頭。將其作為自定義偏好是一種選擇。

OpenAPI 3.1.0 規範

要在 OpenAPI 3.1.0 規範中記錄自定義偏好，請遵循以下指南：

• 在 components.parameters 部分定義 Prefer 標頭：

  components:
    parameters:
      Prefer:
        name: Prefer
        in: header
        description: 客戶端對伺服器行為的偏好
        schema:
          type: string
        example: "handling=strict, timezone=Asia/Taipei"

• 在相關操作中引用此參數：

  paths:
    /example:
      get:
        summary: 示例操作
        parameters:
          - $ref: '#/components/parameters/Prefer'
        responses:
          '200':
            description: 成功回應
            headers:
              Preference-Applied:
                schema:
                  type: string
                description: 指示已應用的偏好

• 對於支持特定自定義偏好的 API，提供更詳細的描述：

  components:
    parameters:
      Prefer:
        name: Prefer
        in: header
        description: |
          客戶端對伺服器行為的偏好。支持的偏好：
          - handling=strict: 強制嚴格的數據驗證
          - timezone=<tz>: 使用指定的時區進行日期/時間操作
        schema:
          type: string
        example: "handling=strict, timezone=Asia/Taipei"

• 對於複雜的偏好設置，使用 object 類型的 schema：

  components:
    parameters:
      Prefer:
        name: Prefer
        in: header
        description: 客戶端對伺服器行為的偏好
        content:
          application/json:
            schema:
              type: object
              properties:
                handling:
                  type: string
                  enum: [strict, lenient]
                timezone:
                  type: string
                  pattern: '^[A-Za-z_]+/[A-Za-z_]+$'
            example:
              handling: strict
              timezone: Asia/Taipei

指南

• 應該(SHOULD)尊重帶偏好的請求

• 必須(MUST)記錄您的 API 是否支持偏好

• 必須(MUST)返回 Preference-Applied 標頭以通知客戶端已接受的偏好

  示例:

  PATCH /my-document HTTP/1.1
  Host: example.org
  Content-Type: application/example-patch
  Prefer: return=representation
  
  [{"op": "add", "path": "/a", "value": 1}]
  
  HTTP/1.1 200 OK
  Content-Type: application/json
  Preference-Applied: return=representation
  Content-Location: /my-document
  
  {"a": 1}

• 如果客戶端的偏好沒有相關操作，必須不(MUST NOT)返回錯誤

• 應該(SHOULD)在您的 API 文件中記錄自定義偏好，並描述伺服器如何尊重該偏好

• DRAFT 應該(SHOULD)在內部 API 入口網站中註冊自定義偏好

• 在發明新的偏好之前，應該(SHOULD)重用自定義偏好以滿足需求

示例

最小回應

POST /robots/{robot-id}/move HTTP/1.1
Host: example.com
Prefer: return=minimal

HTTP/1.1 202 Accepted

異步處理

POST /robots/{robot-id}/stop HTTP/1.1
Host: example.com
Prefer: respond-async

參考資料

• RFC 7240: HTTP 的 Prefer 標頭
• RFC 8144: 在 Web 分佈式創作和版本控制 (WebDAV) 中使用 Prefer 標頭屬性(property)
• IANA HTTP 偏好註冊表

設計參考

• PostgREST Prefer 標頭實現
• ADP-136: Prefer