【実務・中級編】 APIの冪等性（Idempotency）の確保とIdempotency-Keyヘッダー – Web APIアーキテクチャ・データ連携実践ガイド

「二重決済」という悪夢を断ち切る：Idempotency-Keyによる冪等性制御の極意

ネットワークエンジニアとして現場を歩いていると、避けては通れないのが「パケットの不確実性」です。クライアントが送信したリクエストがサーバーに届き、処理が完了したにもかかわらず、その応答（ACKやHTTPレスポンス）がネットワークの瞬断やタイムアウトでクライアントに届かない――。

そんな時、クライアントはどう動くか？当然、「届いていないかもしれない」と判断し、同じリクエストを再送します。これが決済や在庫引き当てのような「副作用を伴う処理」だったら？悪夢の二重処理が確定します。

この「一度行っても、何度行っても結果が同じである」という性質、すなわち冪等性（Idempotency）をどう担保するか。今回は、REST APIの設計において最も実戦的かつ不可欠な Idempotency-Key ヘッダーによる制御について、現場の知見を交えて深掘りします。

—

1. なぜ「冪等性」がAPI設計の生命線なのか

RESTの原則において、GET や HEAD は本質的に冪等ですが、POST はそうではありません。ユーザーが「購入」ボタンを連打した時、あるいはモバイル端末がトンネルに入って通信が途絶えた後に自動リトライした時、サーバー側で「これは同じリクエストだ」と識別できなければ、ビジネスロジックは崩壊します。

ここで登場するのが、[RFC 9110](https://datatypes.org/rfc9110.html) でも示唆されるような「リクエストの識別子」です。クライアント側でユニークなキー（多くはUUID）を生成し、Idempotency-Key ヘッダーに込めて送ることで、サーバーは「このキーの処理は既に終わったか？」を判断できるようになります。

—

2. 通信フロー：パケットの裏側で起きていること

理想的な冪等性制御のシーケンスは、以下のような流れになります。

1. Client: UUIDを生成し、Idempotency-Key: <UUID> を付与してリクエスト送信。
2. Server: DBの冪等性テーブルまたはRedis等のKVSを参照。

未処理の場合：キーを記録（ロック）してビジネスロジックを実行。
処理済みの場合：以前保存したレスポンスをそのまま返す。

3. Client: サーバーからのレスポンスを受信。もしネットワークエラーで再送しても、サーバー側で同じレスポンスが返るため、二重処理は発生しない。

ここでのポイントは、単に「処理済みかチェックする」だけでなく、「同じキーに対しては、初回実行時のレスポンスをキャッシュして再送する」という設計にすることです。

—

3. 実践：Idempotency-Keyの実装例

クライアントサイド (Python/requestsの例)

クライアント側の実装はシンプルです。UUIDを生成し、ヘッダーに載せるだけです。

import requests
import uuid

# クライアント側で一意のキーを生成
idempotency_key = str(uuid.uuid4())

url = "https://api.example.com/v1/orders"
headers = {
    "Idempotency-Key": idempotency_key,
    "Content-Type": "application/json"
}
data = {"item_id": 123, "quantity": 1}

# 再送時も同じ idempotency_key を使い回すのが肝
response = requests.post(url, json=data, headers=headers)

print(f"Status: {response.status_code}")

サーバーサイド (擬似ロジック)

サーバー側では、DBのトランザクション設計が重要です。Idempotency-Key をユニークキーとして持ち、DBのACID特性を利用して「キーの登録」と「処理の実行」をアトミックに行います。

-- 冪等性テーブルの定義例
CREATE TABLE idempotency_records (
    key VARCHAR(255) PRIMARY KEY,
    response_body TEXT,
    status_code INT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

# サーバー側疑似ロジック
def handle_request(key, data):
    # 既に処理済みか確認
    cached = db.execute("SELECT * FROM idempotency_records WHERE key = ?", (key,))
    if cached:
        return cached.response_body # 以前の結果を即座に返す

    # 初回処理
    result = process_order(data)
    
    # 結果を保存
    db.execute("INSERT INTO idempotency_records (key, response_body) VALUES (?, ?)", 
               (key, result))
    return result

—

4. インフラ屋としての現場Tips：デバッグと運用

現場でこの仕組みを運用する際、よくある落とし穴があります。

キーの寿命管理: Idempotency-Key を永久保存するとDBが肥大化します。Redis等のTTL（有効期限）機能を使って、24時間～72時間程度で自動削除する運用が一般的です。
ヘッダーの伝搬: API Gatewayやロードバランサーを挟む場合、Idempotency-Key ヘッダーがバックエンドまで正しく転送されているか確認してください。たまに設定ミスでヘッダーが剥がされることがあります。
リトライ戦略: 500 Internal Server Error や 503 Service Unavailable の場合はリトライすべきですが、400 Bad Request の場合はリトライしても無駄です。クライアント側のロジックで適切に切り分けましょう。

—

最後に：ネットワークは「信頼できない」という前提を持つ

ネットワーク通信は常に「どこかでパケットが消失するリスク」を抱えています。しかし、今回紹介した Idempotency-Key を活用すれば、そのリスクをアプリケーション層で完全に制御下に置くことができます。

美しいAPI設計とは、単にURLが綺麗であることだけを指すのではありません。「ネットワークの不安定さを、エンジニアリングでいかに优雅（ゆうが）に隠蔽するか」。それこそが、シニアなインフラエンジニアが追求すべき美学だと私は考えます。

皆さんの設計するAPIが、いかなるネットワークの嵐の中でも、データの一貫性を守り抜く強靭なものになることを願っています。それでは、また次の深淵でお会いしましょう。