冪等性(べきとうせい)は、同じ操作を繰り返しても、意図した効果が一度の実行と変わらない性質です。APIでは、通信が途切れて再試行しても、注文や請求などの処理を重複させない設計に関わります。
重要なのは、応答が届かなかったことと、処理されなかったことは同じではないという点です。再送の待ち時間だけでなく、同じ操作をどう識別するかを決めます。
タイムアウト後に何が分からないのか
架空の注文APIで、サーバーが注文を作成した直後に通信が切れたとします。利用者側には注文番号が届かず、失敗したように見えます。ここで同じ内容を新規注文として送ると、二つの注文が作られるおそれがあります。
AWSのBuilders Libraryも、失敗時の再試行と副作用の重複を課題として説明しています。依頼者が渡す識別子を使い、同じ意図の要求を識別する方法が紹介されています。AWS: Making retries safe with idempotent APIs
単に入力内容が同じだからといって、同じ操作とは限りません。同じ商品を同じ数量でもう一度注文することはあり得ます。そのため、業務上の一回の依頼を識別する値が必要です。
冪等キーをいつ作り、いつ再利用するか
冪等キーは、一回の操作を識別するためにクライアントなどが発行する値です。再試行するたびに新しいキーを発行すると、受信側は別の操作と判断するため、重複防止になりません。
一つの注文操作を始めるときにキーを作り、応答不明で再送するときは同じキーと同じ入力を使います。内容を変更した別の注文なら、新しい操作として扱います。キーの発行主体や適用範囲はAPIの契約で決めてください。
StripeのAPI v1は、キーに対応する実行済みの結果を保存し、同じキーの再要求に返す例です。同じキーで異なるパラメータを使う場合のエラーや、キーを保持する期間も定めています。これはStripe固有の仕様であり、すべてのAPIが同じ動作をするわけではありません。Stripe: Idempotent requests
状態ごとの応答を決める
次の表は、注文作成APIを設計するときの検討例です。具体的なステータスコードや保存期間は、提供するAPIの仕様として別途決めます。
| 受信時の状態 | 検討する動作 |
|---|---|
| 初めて受け取るキー | 入力を検証し、処理の開始と結果を記録する |
| 同じキー・同じ入力で完了済み | 既存の結果を返し、新しい注文を作らない |
| 同じキー・異なる入力 | 意図しない再利用として拒否する |
| 同じキーで処理中 | 競合を検知し、二重実行せず待機・再照会などへ導く |
| キーの記録が期限切れ | 保持期限後の扱いを仕様化し、必要なら業務IDで照会する |
「処理中」の状態を放置しないことも大切です。実行途中で停止した場合、誰がどの記録を見て復旧するかを決めます。キーが見つからないことだけを理由に、外部での処理まで未実行だと判断しないでください。
キーの保存だけでは重複を防げない
キーの記録と注文の作成を別々に行うと、その間の停止が問題になります。キーだけ保存されて注文がない場合も、注文だけ作られてキーがない場合もあり得ます。AWSは、トークン記録と変更を原子的に扱う必要性を説明しています。AWS: Atomic operations
同じデータベース内で完結するなら、一意性の制約やトランザクションをどう使うかを検討します。外部決済など別システムへの操作が含まれる場合は、ローカルのトランザクションだけで全体を一体化できると考えず、外部側の冪等性、状態照会、復旧手順を組み合わせます。これは構成ごとに検討すべき設計事項です。
再試行の試験に含めるケース
正常な二回送信だけでなく、同時送信、処理完了直後の通信断、記録保存前後の停止、キーと入力の不一致、期限後の再送を試します。「エラーにならない」だけでなく、業務データが一件であることと、利用者が結果を確認できることを確かめてください。
サービス間の処理を分ける際の運用負荷は、モノリスとマイクロサービスの比較でも整理しています。まず、再試行が起こる境界と、重複してはいけない効果を一組ずつ書き出すと、必要な冪等性の範囲が明確になります。