冪等性 (Idempotency) とは、同じ操作を 1 回実行しても複数回実行しても、結果が同じになる性質のことです。数学では f(f(x)) = f(x) と表現されます。Web API の設計において、ネットワーク障害やタイムアウトによるリトライ時に、重複処理を防ぐための重要な概念です。
HTTP メソッドの冪等性は仕様で定義されています。GET、PUT、DELETE は冪等、POST は非冪等 (実行するたびに新しいリソースが作成される可能性がある) です。ここでいう冪等とは、同じリクエストを何度送ってもサーバーに生じる結果が 1 回送ったときと同じになる、という意味です。返ってくるレスポンスまで同一になるとは限らず、たとえば DELETE は 1 回目が 200、2 回目以降は対象が既に無いため 404 を返すことがありますが、これは冪等性に反しません。
短縮 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 にマッピングされます。