[ADP-352] 條件式請求
概述
條件式請求是只有在滿足特定條件時才執行的 HTTP 請求。它們主要用於提高效率並減少不必要的數據傳輸。
指導原則
- API 在適當的情況下應該(SHOULD)支持條件式請求，特別是對於大型資源或經常訪問的數據。
- 實現應該(SHOULD)使用 ETag 結合 If-None-Match 和 If-Match 標頭進行條件式請求。
- 另一種方法是基於日期的條件式請求，使用Last-Modified 結合 If-Modified-Since 和 If-Unmodified-Since。
- 在實現條件式請求時:
- GET 請求應該(SHOULD)使用 If-None-Match 進行緩存並避免不必要的數據傳輸。
- PUT、PATCH 和 DELETE 請求應該(SHOULD)使用 If-Match 來防止更新丟失並確保數據完整性。
- API 必須為條件式請求返回適當的狀態碼:
- 當條件不滿足時，GET 請求返回 304 Not Modified。
- 當條件不滿足時，PUT、PATCH 或 DELETE 請求返回 412 Precondition Failed。
- 錯誤回應必須符合 HTTP Problem(RFC 9457)。
最佳實踐
- 對大型資源或頻繁變化的數據使用條件式請求，以減少頻寬使用。
- 在 API 文件中清楚說明如何支持條件式請求。
- 確保 ETag 生成不會顯著影響經常訪問資源的性能。