【ITニュース解説】API Idempotency: Why Your System Needs It?

APIは、異なるソフトウェア同士が情報をやり取りするための窓口のようなものだ。インターネット上のサービスが連携する際に不可欠な仕組みで、例えばオンラインストアで商品を購入したり、銀行の残高を確認したりする際にもAPIが使われている。しかし、このAPIを使った通信は常に完璧というわけではない。インターネットは不安定な要素を多く含んでおり、通信が途中で途切れたり、処理が遅延したりすることは珍しくない。

特に問題となるのが、クライアント（リクエストを送信する側）がサーバー（リクエストを処理する側）からの応答を受け取れなかった場合だ。クライアントは処理が失敗したと判断し、同じリクエストを再度送ることがある。もしサーバー側で最初のリクエストがすでに処理されていた場合、同じ処理が重複して実行されてしまう。例えば、在庫管理システムで「在庫に100個追加する」というリクエストを送信し、ネットワークの問題で応答が返ってこなかったとする。クライアントは再度同じリクエストを送信し、サーバーは最初の100個の追加処理に加えて、さらに100個を追加してしまう。結果として、本来100個追加されるはずが200個追加されてしまい、データが誤った状態になる。

このような重複処理によるデータ破損を防ぎ、システムの信頼性を高めるために非常に重要な考え方が「멱等性（Idempotency）」だ。멱等性とは、ある操作を何度行っても、システムの状態が同じ結果になる性質を指す。つまり、たとえ同じリクエストが複数回送られてきても、サーバーは最初の1回目と同じように処理し、意図しない副作用（データの重複追加や二重支払いなど）を防ぐ必要がある。これは、特にデータの更新や作成を伴う重要な操作において不可欠な特性と言える。

멱等性を実現するための一般的な方法の一つに、「멱等性キー」と呼ばれる特別な識別子を使用する手法がある。これは、リクエストごとにユニークな文字列を生成し、そのキーをリクエストヘッダーに含めてサーバーに送信する方法だ。クライアントとサーバーは、この멱等性キーをルールに基づいて運用することで、重複処理の問題を回避できる。

クライアント側には二つの重要な責任がある。一つは、新しい操作を行う際には、必ずユニークな멱等性キーを生成し、リクエストに含めること。このキーは、そのリクエストの「身分証明書」のようなもので、二度と同じキーが使われることはないようにする。もう一つは、もしリクエストが失敗し、再試行する場合には、必ず最初のリクエストで使ったものと同じ멱等性キーを再利用することだ。これにより、サーバーはそれが新しいリクエストなのか、それとも以前のリクエストの再試行なのかを判断できるようになる。

一方、サーバー側の責任も大きい。サーバーは、リクエストに멱等性キーが含まれている場合、そのキーを使って過去に同じリクエストが処理され、成功したかどうかをチェックする。もし同じキーで以前に処理が成功し、200番台のHTTPステータスコード（成功を示すコード）でレスポンスを返していた記録があれば、サーバーは実際の処理を再度実行せず、以前に成功した際のレスポンスをそのままクライアントに返す。これにより、重複処理を防ぐことができる。ただし、GETリクエストのようにデータの取得のみを行い、サーバーの状態を変更しない操作については、멱等性キーのチェックやレスポンスの保存は不要だ。なぜなら、何度実行してもシステムの状態は変わらないため、重複処理の問題が発生しないからだ。

この멱等性キーとレスポンスの記録を保存するために、サーバー側には専用のデータベーステーブルを用意することが一般的だ。例えば、id（レコードを識別する主キー）、idempotency_key（クライアントから送られてきた멱等性キー）、http_status_code（成功時のHTTPステータスコード）、http_response（成功時のレスポンスボディ）、そしてcreated_at（レコードが作成された日時）といったカラムを持つテーブルを作成する。これにより、サーバーは受け取った멱等性キーが過去に使われたものかどうか、そしてその際のレスポンスが何であったかを効率的に参照できるようになる。

具体的な実装方法として、APIリクエストがコントローラー（実際のビジネスロジックを処理する部分）に到達する前と、コントローラーからの応答がクライアントに返される後の両方で処理を挟み込む「インターセプター」という仕組みが利用できる。リクエストが来る前に動作するpreHandleメソッドでは、まずリクエストヘッダーから멱等性キーを抽出し、そのキーがすでにデータベースに存在するかどうかを確認する。もし存在し、かつ以前の処理が成功していたら、保存されているレスポンスをクライアントに返し、これ以上実際の処理を進めない。もし初めてのキーであれば、データベースに一時的なレコードを作成し、実際の処理へと進める。

そして、コントローラーが処理を終え、レスポンスが生成された後に動作するafterCompletionメソッドでは、もしそのレスポンスが成功（200番台）であった場合、その멱等性キーとレスポンスの内容をデータベースに保存する。これにより、次回同じ멱等性キーでリクエストが来たときに、キャッシュされたレスポンスを返せるようになる。なお、멱等性キーとレスポンスのデータは永久に保存しておく必要はない。古いデータは不要になり、データベースの容量を圧迫するため、定期的に削除する仕組みも必要だ。これは、例えば「7日以上前の멱等性データを毎日午前2時に削除する」といったスケジューラー（定時実行プログラム）を設定することで実現できる。

このように、APIの멱等性をシステムに導入することは、ネットワークの不確実性から生じるデータ破損や誤処理を防ぎ、システムの信頼性と安定性を大幅に向上させるために不可欠な対策だ。クライアントとサーバーが協力して멱等性キーを適切に管理することで、ユーザーは安心してサービスを利用できるようになり、システムエンジニアはより堅牢なシステムを構築できるようになる。