ADP
API Design PrincipleBETA

繁體中文

English

繁體中文

English

Appearance

[ADP-353] 內容協商 ​

概述 ​

內容協商是一種機制，允許伺服器根據客戶端的偏好選擇資源的最佳表示形式。它為同一資源啟用不同版本的回應(如HTML、XML、JSON等)，從而增強API的可訪問性。

內容協商主要有兩種類型:

  1. 主動式(伺服器驅動):伺服器根據客戶端聲明的偏好選擇表示形式。
  2. 被動式(客戶端驅動或代理驅動):客戶端在請求中指定表示形式。

伺服器驅動協商是最常用的方法，HTTP 客戶端使用 Accept 標頭告訴伺服器它們將接受哪些內容類型。

TIP

💡 除非您詳細記錄協商過程，否則不應處理客戶端驅動的協商。

指導原則 ​

  • 應該(SHOULD)根據 RFC 返回與 application/json 兼容的 MIME 類型。
  • 應該(SHOULD)設計特定的API來處理國際化偏好，而不是依賴 Accept-Language 標頭。
  • 絕不(MUST NOT)能使用User-Agent進行內容協商。

相關HTTP標頭 ​

請求 ​

  • Accept
  • Accept-Encoding
  • Accept-CH

有關這些標頭的詳細資訊，請參閱ADP-121。

回應 ​

  • Content-Type，參見ADP-126
  • Content-Encoding
  • Language
  • Vary

有關這些標頭的詳細資訊，請參閱ADP-121。

示例 ​

設計一個API，根據需求通過URL或圖像類型獲取資產 ​

http
GET /assets/asset-id HTTP/1.1
Accept: image/jpeg

HTTP/1.1 200 OK
Content-Type: image/jpeg
(二進制數據)
http
GET /assets/asset-id HTTP/1.1
Accept: application/json

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

{
  "url": "....",
}

設計一個API，對同一資源採用不同的修飾符 ​

http
GET /api-principles/1
Accept: application/vnd.my-corp.alive-app.api-principle.simplified+json

200
Content-Type: application/vnd.my-corp.alive-app.api-principle.simplified+json

{
  "title": "應該採用最佳實踐",
  "principleId": 1
}
http
GET /api-principles/1
Accept: application/vnd.my-corp.alive-app.api-principle+json

200
Content-Type: application/vnd.my-corp.alive-app.api-principle+json

{
  "title": "應該採用最佳實踐",
  "principleId": 1,
  "examples": [],
  "references": [],
  "designThing": "...."
}

參考資料 ​