Skip to content
ADP
API Design PrincipleBETA

[ADP-120] HTTP 標頭

HTTP 標頭是在請求和回應中定義的元數據,用於正式描述它們。API 設計者應該了解如何使用現有的 HTTP 標頭來完成他們的 API 設計,或者在沒有現有標頭滿足需求時創建自定義標頭。

指引

  • API 設計者應該(SHOULD)支持常見的 HTTP 標頭。
  • 只有在現有標頭無法滿足特定需求時,才應(SHOULD)創建自定義標頭。
    • DRAFT 由於RFC不建議使用X-作為自定義標頭前綴,因此如果需要,應該使用VVTK-作為自定義標頭的前綴。
  • DRAFT 當客戶端提供請求標頭不方便時,可以(MAY)將請求標頭的功能複製為查詢參數。在這些情況下,查詢參數的名稱應該與標頭名稱相似,遵守所有查詢參數名稱的規則。例如,請求標頭 If-Match 將被表示為查詢參數 ifMatch

    大小寫

    如果你的項目採用 SNAKE_CASE 作為查詢參數命名法,則在這種情況下,大小寫應為 if_match

常見 HTTP 標頭

參見 ADP-121

自定義標頭

參見 ADP-36

最佳實踐

  1. 在整個 API 景觀中保持標頭使用的一致性。
  2. 驗證和淨化標頭值以防止安全漏洞。
  3. 使用適當的標頭進行身份驗證和授權。
  4. 在創建自定義標頭之前,優先使用標準標頭。
  5. 在 API 文件中包含相關標頭。

參考資料

Changelog

  • 2024.09.30 Add header as query parameters, referred from IBM api docs