API リクエストの重複排除を行い、リクエストを安全に再試行しましょう。
「API リクエストの冪等性」とは、同じ操作を複数回実行しても、最初のトライと同じ結果が得られる能力のことです。これは、ネットワークの本質的な信頼性の低さを克服し、重要な操作が失敗した場合に高い対応能力を提供するための設計原則です。
GET リクエストの冪等性
Smartpay API では、GET リクエストの冪等性を保証しており、GET リクエストをいつでも安全に再試行していただけます。ネットワークは本質的に信頼性が低く、一定回数の失敗の発生が予測されます。多くの場合、サーバー側の操作が成功したかどうかはクライアント側からは不明確であり、操作の再試行が安全かどうか分かりません。たとえば、返金リクエストの途中で接続が切れた場合などです。そのため、クライアントがリクエストの失敗をサーバーに確認する方法が必要であり、冪等性によりそのためのメカニズムが提供されます。
その他のリクエストに対する冪等性
冪等キーを含めると、POST、PUT、および PATCH リクエストが冪等であることが保証され、API に操作の重複排除に必要なすべての作業を実行するよう指示します。このように、Smartpay のサーバーがキーを最初に受信してから6時間以内に再試行したリクエストが実行された場合、クライアントは冪等キーを含むリクエストを安全に再試行することができます。この方法により、たとえばネットワークの接続エラーが原因で返金の作成リクエストに対するレスポンスがない場合、クライアントは元のリクエストと同じ冪等キーを使ってリクエストを再試行し、返金が一つだけ作成されることを保証できます。
冪等リクエストの作成
冪等キーは、リクエストのIdempotency-Key: ヘッダーに送信されます。このキーの値はクライアントによって生成され、サーバーが6時間の枠内で同じリクエストの後続の再試行を明確に認識するために十分なレベルで一意である必要があります。true に設定した Idempotency-Replay ヘッダーにより、サーバーから再実行される以前実行されたリクエストを特定できます。
冪等キーの一意性と衝突
一意のキーの作成方法は自由ですが、衝突を避けるためにエントロピーが十分に高いランダムな文字列 (V4 UUIDs など) を推奨します。再試行の際、Smartpay の冪等層は、受信したリクエストのパラメーターと元の冪等キーにリンクされている元のリクエストを比較し、これらが一致しない場合は衝突として処理します。衝突の場合、Smartpay API は 422 Unprocessable Entity を返します。