1. 序章

この記事では、べき等演算とは何か、べき等が役立つ理由、およびRESTでのべき等について説明します。

2. べき等とは何ですか？

簡単に言えば、結果を変更せずにべき等演算を複数回実行できます。

さらに、最初の正常な実行後に、操作によって副作用が発生してはなりません。

2つの簡単な例を見てみましょう。

2.1. 絶対値

絶対値を返す関数はべき等です。 同じ番号に何度適用しても、常に同じ結果が返されます。

関数について考えてみましょう。

次に、次のことが当てはまります。

例：

対照的に、数値の符号を反転する関数はべき等ではありません。

それで：

例：

2.2. アドレスを更新

べき等操作のもう1つの実用的な例は、システム内のユーザーの連絡先の詳細を更新することです。 電話番号のみを更新するとします。 この更新の副作用は、確認コードを含むテキストメッセージを新しい番号に送信することです。 考えられるシナリオは3つあります。

  • 最初の更新メッセージが正常に処理され、システムで番号が更新され、テキストメッセージが送信されました。 更新メッセージが再度送信されても、何も起こりません。 また、テキストメッセージは2回送信されません。
  • 最初の更新は失敗します。 システムは更新されず、テキストメッセージは送信されません。 2回目の更新が成功すると、システムが更新され、テキストメッセージが送信されます。
  • 最初の更新は失敗します。 別の更新が送信される前に、ユーザーはシステムで非アクティブ化されます。 システム状態が変更されたため、電話番号の2回目の更新は影響しません。

3. なぜべき等？

べき等は、同じ要求が同じシステム状態につながることを保証し、意図せずに複数回アクションが実行されることはありません。

例として、送信者からのリクエストを見てみましょう S 支払いサービスを介して送金する PS 受信機に R。 

3.1. 非べき等の例

要求の非べき等バージョンは次のとおりです。

最初の試行では、Sは$10をRに送信する要求を送信します。 PSはメッセージを受信します。 ただし、実際の転送は失敗します。 PS は、ネットワーク障害のためにそのメッセージを受信しないSにエラーメッセージを返します。

S は転送が成功したかどうかわからないため、再試行します。 今回はRへの転送が成功し、PSがSに確認メッセージを送信します。 この場合も、確認は失敗し、Sは転送が成功したかどうかを認識しません。

したがって、彼は3回目の試みをします。 PS はメッセージを受信し、それを新しいリクエストと見なし、Rに送金し、Sに確認を返します。

同じ支払いを再試行し、2回送信しないことを意図しているため、これはべき等の要求ではありません。

3.2. べき等キー

支払いは、べき等が役立つ理由を説明する良い例です。 前の例では、 S がすでに転送が成功したことを知らずにリタイアするため、Rへの支払いが複数回実行されることを確認しました。

操作がべき等であった場合、これは当てはまりませんでした。 しかし、 PS は、 S が同じ支払いを再試行したばかりで、Sに$10の2回目の支払いを送信したくないことをどのように知るのでしょうか。

これを実現するために、SはPSへの要求にべき等キーを含めます。 このキーは、たとえば、UUIDにすることができます。 PS が同じべき等キーを持つ要求を受信した場合、それは再試行であることがわかります。 以前にキーを見たことがない場合は、それが新しいリクエストであることを認識しています。

前の例のべき等バージョンを見てみましょう。

ここで、最初の試行と最初の再試行は、要求にべき等キー（この例では 65TH68M5）が含まれていることを除いて、非べき等バージョンと同じです。

重要な違いは2回目の再試行です。PSはメッセージを受信し、同じべき等キーを持つメッセージがすでに正常に処理されていることを検出し、送金せずにSに確認を返します。 R再び。

ここで、べき等の利点は、Sが二重支払いを心配することなく、何度でも再試行できることです。 PSはSを心配する必要はありません。 は、メッセージを受信していない場合に S が再試行できることを知っているため、確認を受信します。

このアプローチの欠点は、PSが受信したすべてのキーを保存する必要があることです。 リクエストが少ない場合は、これで問題ない可能性があります。 ただし、リクエストの頻度が非常に高い場合は、問題が発生する可能性があります。 解決策は、しばらくしてべき等キーを期限切れにすることです。

4. べき等とREST

4.1. 概要

べき等性がHTTP動詞にどのように適用されるかを簡単に見てみましょう。これは、RESTAPIを構築するときに理解することが重要です。 すべてのHTTP動詞の非常に詳細なリファレンスは、 RFC7231にあります。

次の表は、どの動詞がべき等であるか（またはすべきであるか）を示しています。

4.2. べき等演算

GET、HEAD、およびOPTIONは、データのみを読み取るため、明らかにべき等ですが、リソースを作成、更新、または削除することはありません。

PUTは、リソースを更新するか、存在しない場合は新しいリソースを作成するため、べき等です。同じ更新を複数回送信した場合、リソースは変更されません。

4.3. 非べき等演算

POSTは新しいリソースを作成し、再度呼び出されると通常は別のリソースを作成するため、べき等である必要はありません。 ただし、べき等演算として実装することもできます。

PATCH操作はリソースを部分的に更新し、必ずしもべき等である必要はありません。 PUTとPATCHの違いをよりよく理解するために、例を見てみましょう。

オンラインショップのショッピングカートに商品を追加したいとします。 PUTを使用する場合は、すでにカートに入っているすべてのアイテムを含む、完全なショッピングカートデータを送信する必要があります。 PATCHを使用すると、追加するアイテムのみを送信でき、カートに既にあるアイテムのリストに追加されます。

再度PATCHリクエストを送信すると、同じアイテムが再度追加されます。 もちろん、POSTに関しては、べき等のPATCHを実装することもできます。

4.4. HTTP応答

べき等演算への複数の呼び出しが必ずしも同じHTTP応答をもたらすとは限らないことに注意することが重要です。

たとえば、PUTは、リソースが作成された場合は201（作成済み）を返し、リソースが更新された場合は 200 （OK）または 203 （コンテンツなし）を返します。

たとえば、DELETEは、実際の削除が行われたときに 200 （OK）または 204 （コンテンツなし）を返すことができます。 それ以降の呼び出しは404（見つかりません）を返します。

5. 結論

この記事では、べき等の意味、べき等の利点、およびRESTとの関係について説明しました。

べき等の一般的な意味は簡単に理解できますが、APIの設計時に副作用やHTTP応答などの微妙な点をすべて考慮するのは非常に難しい場合があります。