[ADP-367] HTTP Profile

概述

RFC 6906 引入了 "profile" 鏈接關係類型，允許 API 設計者傳達超出媒體類型本身描述的額外語義。

指導

• 具有 audience≥PARTNER_EXTERNAL 的 API 應該(SHOULD)使用 "profile" 鏈接關係來表示資源表示符合一個或多個配置文件。

• 配置文件應該(SHOULD)被清楚定義和記錄。文件應包括:

  • 配置文件的唯一標識符(URI)。
  • 對配置文件施加的額外語義、約束和慣例的描述。

• 在適用的情況下，應(SHOULD)在 HTTP 標頭中包含 "profile" 鏈接關係以傳達配置文件資訊。例如:

  Link: <http://example.com/profiles/resource-profile>; rel="profile"

• 配置文件鏈接應該(SHOULD)是絕對 URI 而不是相對 URI。 URI 必須位於與 API 端點相同的 URL 命名空間內。例如，如果所有 API 端點都位於 https://api.test.com/v1/，則配置文件 URI 也應位於相同的上下文路徑中(例如，https://api.test.com/v1/payment/profiles/payment-method+v1)。

• 如果決定要支援 REST 成熟度層級 3, "profile" 鏈接關係應(SHOULD)嵌入超媒體格式(例如，JSON、HAL)中，以表示特定資源符合配置文件。例如:

  {
    "name": "範例資源",
    "description": "這是一個範例資源。",
    "_links": {
      "profile": {
        "href": "http://example.com/profiles/sample-resource"
      }
    }
  }

• 配置文件應該(SHOULD)進行版本控制，以適應隨時間的變化和改進。配置文件 URI 在適用時應包含版本資訊。例如:

  Link: <http://example.com/profiles/resource-profile/v1.0>; rel="profile"

• 配置文件應該(SHOULD)設計為促進不同系統之間的互操作性。它們應該指定驗證規則，以確保資源表示符合配置文件。

• 更新配置文件時，應(SHOULD)注意保持向後兼容性。應清楚記錄已棄用的元素，並應給予客戶端充足的時間過渡到新版本。

• API 設計者應(SHOULD)考慮使用 OpenAPI schema 作為配置文件的基礎。

• 配置文件可(MAY)與內容協商結合使用，允許客戶端請求資源的特定表示。

• API 文件應(SHOULD)清楚解釋如何解釋和使用配置文件，包括對客戶端行為的任何影響。

• DRAFT 應(SHOULD)考慮創建一個配置文件註冊表，以管理和記錄所有可用的配置文件。

示例

OpenAPI 中的配置文件聲明

openapi: 3.0.0
info:
  title: 範例 API
  version: 1.0.0
paths:
  /resources:
    get:
      responses:
        '200':
          description: 成功回應
          headers:
            Link:
              schema:
                type: string
              example: '<http://example.com/profiles/resource/v1>; rel="profile"'

參考

• RFC 6906: The 'profile' Link Relation Type
• HAL - Hypertext Application Language

設計參考

• OTTO API Guidelines
• Microsoft REST API Guidelines