冪等性 (Idempotency) とは、同じ操作を 1 回実行しても複数回実行しても、結果が同じになる性質のことです。数学では f(f(x)) = f(x) と表現されます。Web API の設計において、ネットワーク障害やタイムアウトによるリトライ時に、重複処理を防ぐための重要な概念です。
HTTP メソッドの冪等性は仕様で定義されています。GET、PUT、DELETE は冪等 (何度実行しても同じ結果)、POST は非冪等 (実行するたびに新しいリソースが作成される可能性がある) です。
短縮 URL サービスの API 設計で冪等性は核心的な課題です。同じ URL を短縮するリクエストを 2 回送った場合、2 つの異なる短縮 URL が生成されるべきか、同じ短縮 URL が返されるべきか。冪等な設計では、同じ入力に対して常に同じ短縮 URL を返します。これにより、ネットワークエラーでリトライした場合でも、重複した短縮 URL が生成されません。
冪等性を実現する一般的な手法は、Idempotency Key (冪等キー) の使用です。クライアントがリクエストに一意のキー (UUID など) を付与し、サーバーはそのキーに対する処理結果をキャッシュします。同じキーのリクエストが再度来た場合、処理を再実行せずにキャッシュされた結果を返します。Stripe の決済 API がこの手法の代表例です。
短縮 URL サービスでの冪等性の実装は、URL の正規化と組み合わせて行います。入力 URL を正規化した上でハッシュを計算し、同じハッシュに対しては同じショートコードを返す設計です。これにより、「https://example.com/page」と「https://example.com/page/」が同じ短縮 URL にマッピングされます。関連書籍は Amazon でも探せます。