「冪等（べきとう）なAPI」とは？

冪等（べきとう）なAPIエンドポイントとは、1回呼んでも10回呼んでも同じ結果になるもののこと。同一のリクエストを繰り返しても、効果が重複して発生しないからだ。ダブルクリックが二重請求に化けるのを止めているのが、この性質にあたる。

解こうとしている問題は、ネットワークがリクエストの途中で落ちることだ。決済の呼び出しがタイムアウトすると、クライアントにはサーバーが処理したかどうか分からないので、再送する。冪等でなければその再送がカードに二度請求しかねないが、冪等であれば再送はいつでも安全になる。標準的な実装が冪等キーだ。クライアントがリクエストに一意のIDを付け、サーバーは最初の実行結果をそのキーの下に記録し、同じキーの繰り返しには再実行ではなく保存済みの応答を返す。HTTPのメソッドには定義上すでに冪等なものもある。二度削除しても削除された状態のままだからだ。一方POSTは冪等ではなく、だからこそ決済APIはPOSTにキーを取り付ける。決済ページの「送信ボタンを二度押さないでください」という警告は、その仕組みを省いたと白状している表示だ。

エレベーターのボタンだ。1回押しても、ため息をつきながら7回押しても、来るエレベーターは1台。リクエストは一度だけ登録され、繰り返しはすべて同じ結果に対応づけられるからだ。7台のかごを送り出すエレベーターがあったなら、それは冪等でない決済エンドポイントということになる。