[ADP-366] 冪等性

指導原則

• 在任何情況下，GET、PUT 和 DELETE 方法必須(MUST)是冪等的。
• 應該(SHOULD)為 POST 和 PATCH 方法實現冪等性。
  • 有關實現細節，請參見 HTTP 標頭 - Idempotency-Key。

實現細節

Idempotency-Key 標頭

在為 POST 或 PATCH 請求實現冪等性時:

1. 客戶端應該為每個請求包含一個帶有唯一值的 Idempotency-Key 標頭。
2. 服務器必須將 Idempotency-Key 存儲在數據庫或緩存中，以管理一致的 API 行為。
3. 如果服務器收到一個之前見過的 Idempotency-Key 的請求:
   • 如果原始請求成功，返回相同的回應。
   • 如果原始請求失敗，服務器可以重試該操作。
   • 如果原始請求仍在進行中，服務器應該返回 409 Conflict 狀態。

示例:

POST /orders HTTP/1.1
Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000

冪等性窗口

• 服務器應該定義一個保證冪等性的時間窗口。
• 在此窗口過期後，服務器可以忘記 Idempotency-Key 並將請求視為新請求。

參考資料

• https://developer.mozilla.org/en-US/docs/Glossary/Idempotent

• https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/

  • 注意:這是草案，以後可能會有變動。

• https://eda-visuals.boyney.io/visuals/understanding-idempotency

• https://www.youtube.com/watch?v=t99NvIazD68

Changelog

• 2024.09.24 Remove unwanted /api path in the samples