冪等

如果一個 HTTP 方法的預期伺服器效果,在傳送單個請求時與傳送多個相同請求時相同,則該方法是冪等的。

HTTP 規範定義了多種 HTTP 方法及其語義,其中包括它們是否冪等。所有安全方法都是冪等的,PUTDELETE 方法也是。而 POSTPATCH 方法則不保證冪等。

客戶端可以安全地重試使用冪等方法的請求,例如,在不確定請求是否已到達伺服器的情況下。如果多個相同的請求碰巧到達伺服器,只要方法是冪等的,就不會造成任何損害。

HTTP 規範僅根據客戶端對伺服器的**預期**效果來定義冪等性。例如,POST 請求旨在向伺服器傳送資料,而 DELETE 請求旨在刪除伺服器上的資源。實際上,伺服器有責任確保其公開的路由符合這些語義。

注意: 雖然強烈建議伺服器遵循 HTTP 規範所規定的語義,但規範並未強制要求。在實際環境中,沒有什麼能阻止伺服器在冪等 HTTP 方法下暴露一個非冪等的端點,儘管這可能會讓客戶端感到驚訝。

此外,請記住

  • 使用冪等方法的請求不一定意味著請求對伺服器沒有副作用,而僅表示客戶端沒有預期任何副作用:例如,伺服器可能會記錄接收每個請求的時間。
  • 每次請求返回的響應可能不同:例如,第一次呼叫 DELETE 可能會返回 200,而後續呼叫則可能返回 404

示例

GET /pageX HTTP/1.1 是冪等的,因為它是一個安全(只讀)方法。如果伺服器上的資料在此期間更新,連續呼叫可能會向客戶端返回不同的資料。

POST /add_row HTTP/1.1 不是冪等的;如果多次呼叫,它會新增多行。

http
POST /add_row HTTP/1.1
POST /add_row HTTP/1.1   -> Adds a 2nd row
POST /add_row HTTP/1.1   -> Adds a 3rd row

DELETE /idX/delete HTTP/1.1 是冪等的,即使返回的狀態碼在不同請求之間可能會改變。

http
DELETE /idX/delete HTTP/1.1   -> Returns 200 if idX exists
DELETE /idX/delete HTTP/1.1   -> Returns 404 as it just got deleted
DELETE /idX/delete HTTP/1.1   -> Returns 404

另見