ADP
API Design PrincipleBETA

繁體中文

English

繁體中文

English

Appearance

[ADP-133] If-None-Match ​

概述 ​

If-None-Match 標頭是一個條件式 HTTP 請求標頭，允許客戶端根據資源的 ETag 發出條件請求。它主要用於快取驗證和防止不必要的數據傳輸。

目的 ​

If-None-Match 標頭的主要目的是:

  1. 驗證快取的資源
  2. 防止不必要的數據傳輸
  3. 實現樂觀並發控制

指導原則 ​

  • API 實現者應該(SHOULD)支持 GET 和 HEAD 請求的 If-None-Match 標頭，以實現高效快取。
  • 伺服器應該(SHOULD)為可快取的資源生成並包含 ETag。
  • 當客戶端擁有資源的快取副本時，應該(SHOULD)在請求中包含 If-None-Match 標頭。
  • 在實現 PUT、POST 或 PATCH 操作時，伺服器應該(SHOULD)遵守 If-None-Match 標頭以防止意外覆蓋。
  • API 文件應該(SHOULD)清楚解釋 API 中如何使用 If-None-Match，包括任何特定資源的行為。

用法 ​

語法 ​

http
If-None-Match: <etag_value>
If-None-Match: <etag_value>, <etag_value>, ...
If-None-Match:
  • <etag_value>: 資源的 ETag 值
  • *: 匹配任何現有實體

行為 ​

  • 對於 GET 和 HEAD 請求:

    • 如果資源的 ETag 與提供的任何 ETag 匹配，伺服器應該回應 304 (Not Modified) 狀態。
    • 如果 ETag 不匹配，伺服器應該回應 200 OK 並返回完整資源。

  • 對於 PUT、POST 和 PATCH 請求:

    • 如果 ETag 匹配，伺服器應該回應 412 (Precondition Failed) 狀態。
    • 如果 ETag 不匹配，伺服器應該正常處理請求。

示例 ​

請求 ​

http
GET /users/123 HTTP/1.1
Host: example.com
If-None-Match: "abc123", "def456"

回應 (未修改) ​

http
HTTP/1.1 304 Not Modified
ETag: "abc123"

回應 (已修改) ​

http
HTTP/1.1 200 OK
Content-Type: application/json
ETag: "ghi789"
{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com"
}

相關 ADP ​

參考資料 ​

Changelog ​

  • 2024.09.24 Remove unwanted /api path in the samples