[ADP-121] 常見的 HTTP 標頭
reviewing phase 1
直接連結到各標頭 ADP
指導原則
- 應該(SHOULD)支援下表所描述的常見 HTTP 標頭。
- 應該(SHOULD)參考 RFC 9110 中的其他常見 HTTP 標頭。
- 在創建自定義標頭之前，可以(MAY)查看 IANA: 訊息標頭 和 維基百科: HTTP 標頭列表 中的常見 HTTP 標頭列表。
請求標頭
| 標頭 | 類型 | 描述 | RFC 來源 |
|---|---|---|---|
| Accept | 字串 | 可接受的回應主體媒體類型。對於有回應主體的請求是必需的。可以是上面列出的媒體類型之一，結合包含資源設定檔 URI 的設定檔參數。例如：application/hal+json;profile="https://api.doc/profiles/checkout/delivery-methods+v1"。 | RFC 9110，第 12.5.1 節 |
| Authorization | 字串 | 用於授權訪問 API 的 OAuth 2.0 bearer 令牌。所有請求都需要。例如：Bearer <Access token>。 | RFC 9110，第 11.6.2 節 |
| Content-Type | 字串 | 請求主體的媒體類型。當請求主體包含數據時是必需的。可以是上面列出的媒體類型之一，結合包含資源設定檔 URI 的設定檔參數。例如：application/hal+json;profile="https://api.otto.de/portal/profiles/checkout/delivery-methods+v1"。 | RFC 9110，第 8.3 節 |
| If-Match | 字串 | 可選。使請求成為條件性的，只有當目標資源的 ETag 與此標頭中提供的 ETag 值匹配時才成功執行。例如：If-Match:"4711bfc13a4712"。 | RFC 9110，第 13.1.1 節 |
| If-None-Match | 字串 | 可選。使請求成為條件性的，只有當目標資源的 ETag 與此標頭中提供的 ETag 值不匹配時才成功執行。例如：If-None-Match:"4711bfc13a4712"。 | RFC 9110，第 13.1.2 節 |
| X-Request-ID | 字串 | 每個請求的唯一標識符。用於跨多個系統追踪和關聯請求。 | 非標準 |
| Range | 字串 | 只請求實體的一部分。用於分塊下載文件或恢復中斷的下載。 | RFC 9110，第 14.2 節 |
| Cache-Control | 字串 | 請求和回應中緩存機制的指令。控制緩存行為，如 no-cache、no-store 和 max-age。 | RFC 9111，第 5.2 節 |
| User-Agent | 字串 | 不得使用。應改用客戶端提示相關標頭。 | RFC 9110 |
| Sec-CH-UA | 字串 | 用戶代理客戶端提示。以更保護隱私的方式提供有關用戶代理的資訊。 | RFC 8942 |
| Sec-CH-UA-Mobile | 字串 | 指示用戶代理是否在移動設備上。 | RFC 8942 |
| Sec-CH-UA-Platform | 字串 | 提供用戶代理運行平台的資訊。 | RFC 8942 |
| If-Modified-Since | 字串 | 使請求成為條件性的，只有當資源自指定日期以來已經修改時才成功執行。例如：If-Modified-Since: "Wed, 21 Oct 2015 07:28:00 GMT"。 | RFC 9110，第 13.1.3 節 |
| If-None-Modified-Since | 字串 | 可選。使請求成為條件性的，只有當資源自指定日期以來未修改時才成功執行。例如：If-None-Modified-Since: "Wed, 21 Oct 2015 07:28:00 GMT"。 | RFC 9110，第 13.1.4 節 |
| If-Range | 字串 | 允許客戶端在資源自指定日期以來未改變時請求資源的一部分。如果資源已經改變，客戶端將接收到整個資源。 | RFC 9110，第 14.2.1 節 |
回應標頭
| 標頭 | 類型 | 描述 | RFC 來源 |
|---|---|---|---|
| Cache-Control | 字串 | 控制瀏覽器和共享緩存中緩存的指令。 | RFC 9111，第 5.2 節 |
| Content-Length | 數字 | 返回的回應主體內容的長度（以字節為單位）。 | RFC 9110，第 8.6 節 |
| Content-Type | 字串 | 返回的回應主體的媒體類型。反映相關發送請求的 Accept 標頭，除非服務器無法滿足客戶端的要求。可以是 application/json 或 application/hal+json 與資源設定檔 URI 的設定檔參數的組合。 | RFC 9110，第 8.3 節 |
| Content-Disposition | 字串 | 指定瀏覽器中內容的顯示樣式。 | RFC 6266，第 4.1 節 |
| Date | 字串 | 回應的時間戳，採用 HTTP-date 格式。例如：Thu, 7 Jul 2022 16:30:00 GMT。 | RFC 9110，第 6.6.1 節 |
| Deprecation | 字串 | 資源被棄用的具體時間點。 | RFC 8594 |
| ETag | 字串 | 資源特定版本的標識符。可以是 GET 或 HEAD 請求回應的一部分，用於確定資源的兩個表示是否相同。使用先前請求的 ETag 回應標頭值作為後續請求中的 If-Match: <entity tag> 或 If-None-Match: <entity tag> 請求標頭，以對資源進行更改（通過 POST、PUT、PATCH）或僅在有變更時檢索負載（通過 GET、HEAD）。參考上表請求標頭中的 If-Match 和 If-None-Match。 | RFC 9110，第 8.8.3 節 |
| Location | 字串 | 資源的 URI。通常在創建新資源後發送此回應標頭。 | RFC 9110，第 10.2.2 節 |
| Sunset | 字串 | 資源不再可用的具體時間點，參見 RFC 8594，第 3 節。 | RFC 8594 |
| Set-Cookie | 字串 | 從服務器向用戶代理發送 cookie。用於會話管理、個性化和追踪。 | RFC 6265 |
| WWW-Authenticate | 字串 | 指示應該使用的身份驗證方案來訪問請求的實體。在 401 Unauthorized 回應中使用，提示客戶端進行身份驗證。 | RFC 9110，第 11.6.1 節 |
| Allow | 字串 | 列出資源支持的 HTTP 方法集。在 405 Method Not Allowed 回應中使用，告知客戶端允許的方法。 | RFC 9110，第 10.2.1 節 |
| Retry-After | 字串 | 指示用戶代理在發出後續請求之前應等待多長時間。在 503 Service Unavailable 回應中使用，告知客戶端何時重試請求。 | RFC 9110，第 10.2.3 節 |
| X-RateLimit-Limit | 字串 | 指示當前期間客戶端允許的請求數量。用於速率限制，告知客戶端其配額。 | 非標準 |
| X-RateLimit-Remaining | 字串 | 指示當前期間剩餘的請求數量。用於速率限制，告知客戶端其剩餘配額。 | 非標準 |
| X-RateLimit-Reset | 字串 | 指示速率限制何時重置。用於速率限制，告知客戶端重置時間。 | 非標準 |
| X-Request-ID | 字串 | 每個請求的唯一標識符。用於跨多個系統追踪和關聯請求。 | 非標準 |
關聯 ADPs
參考
- https://datatracker.ietf.org/doc/html/rfc9110
- http://en.wikipedia.org/wiki/List_of_HTTP_header_fields
Changelog
2024.09.30Addif-modified-since,if-none-modified-since,if-range.