RESTful APIにおける冪等性について
2024/06/12
社内LT会でRESTful APIにおける冪等性というテーマで発表をしたので、記事にも残そうと思います。
LTの資料はあくまでも社内用なので、ここには公開はしません。でも発表資料と同じくらいの記事内容にはなっています。
下図ではシステムがもう片方のシステムに「特定の情報をくれ」というリスクストを渡しています。
リクエストを受け取ったシステムはその内容に応じて、適切な情報をレスポンスとして返しています。
この情報をやりとりする矢印の部分がRESTful APIになります。
また、RESTful APIには以下の5つのメソッドがあります。
エンジニア以外の方にはあまり聴き馴染みのない言葉かもしれません。
エンジニアをやっていてもあまり聴かない言葉でもあります。
ちなみにRESTful APIにおいては「GET」「PUT」「DELETE」の3つのメソッドが冪等性が保証されるべきメソッドになります。
つまり、この3つのメソッドは何回操作実行しても結果が同じにならなければいけません。
ではここでいう「結果が同じ」とはなんでしょうか。
何をもって結果が同じとみなすのでしょうか。
ただ、これだけでは意味がわからないというか腑に落ちない方もいるかもしれません。
以下で解説したいと思います。
図示するとこんな感じです。ちなみに以降に例として出てくるシステムやRESTful APIは架空なので存在しません。
ユーザ管理システムにユーザが4人登録されていて、それとは別に外部システムがあるという状態です。
これを前提として、GETメソッドとDELETEメソッドを例に解説していきます。
外部システムくんがユーザ管理システムくんにIDが3番のユーザ情報をくれとリクエストしています。
それに対してIDが3番である「さとう あお」の情報を正常というステータスと一緒に、外部システムくんにレスポンスとして返しています。
直感的にわかるかもしれませんが、この操作は1回やっても5回やっても1000回やっても同じ結果になります。
レスポンスは常に同じなのはもちろん、データの取得しかしていないのでデータ状態も同じです。
これは冪等性が保証されているといえます。
外部システムくんがユーザ管理システムくんにIDが4番のユーザ情報を削除してくれとリクエストしています。
それに対してIDが4番である「おしお おれんじ」の情報を削除した上で、正常に削除した旨のレスポンスを外部システムくんに返しています。
ではこの操作をもう1回行ったらどうなるでしょうか。
1回目と同様に、外部システムくんがユーザ管理システムくんにIDが4番のユーザ情報を削除してくれとリクエストしています。
1回目で削除したので、IDが4番のユーザがいないので、HTTP404(Not Found)というエラーがレスポンスとして返されます。
ではこれは冪等性が保証されているといえるでしょうか。結果が同じといえるでしょうか。
結論をいうと、これは冪等性が保証されています。
なぜかというと、データの状態が1回目も2回目も同じだからです。
どちらもDELETEメソッドが実行されたあとはユーザが3人になっています。
4人だったのが削除されたから3人になったのか、もともと3人だったのかの違いはあれど、ユーザが3人になったという状態は同じです。
つまりレスポンスは関係ないのです。冪等性を保証する上で考えるべきは実行後のデータ状態です。
これがRESTful APIにおける冪等性の肝となります。
ここまで読んでくださっていれば、なんとなくは理解いただけたかと思います。
メソッドってなに？とか、HTTPステータス（200,204,404）ってなに？とか気になった方は別途調べてみてください。
というわけで不足分を読者にぶん投げたところでおわりです。
https://qiita.com/sfp_waterwalker/items/765abc2b53cc11d5e367
LTの資料はあくまでも社内用なので、ここには公開はしません。でも発表資料と同じくらいの記事内容にはなっています。
RESTful APIとは
下図ではシステムがもう片方のシステムに「特定の情報をくれ」というリスクストを渡しています。
リクエストを受け取ったシステムはその内容に応じて、適切な情報をレスポンスとして返しています。
この情報をやりとりする矢印の部分がRESTful APIになります。
また、RESTful APIには以下の5つのメソッドがあります。
- GET：データの取得
- POST：データの作成
- PUT：データの更新
- PATCH：データの部分更新
- DELETE：データの削除
冪等性（べきとうせい）とは
エンジニア以外の方にはあまり聴き馴染みのない言葉かもしれません。
エンジニアをやっていてもあまり聴かない言葉でもあります。
ちなみにRESTful APIにおいては「GET」「PUT」「DELETE」の3つのメソッドが冪等性が保証されるべきメソッドになります。
つまり、この3つのメソッドは何回操作実行しても結果が同じにならなければいけません。
ではここでいう「結果が同じ」とはなんでしょうか。
何をもって結果が同じとみなすのでしょうか。
結論
RESTful APIにおける冪等性で指す「結果が同じ」というのは「レスポンス」ではなく「リソース（データ）」のことである。
ただ、これだけでは意味がわからないというか腑に落ちない方もいるかもしれません。
以下で解説したいと思います。
具体例で解説
図示するとこんな感じです。ちなみに以降に例として出てくるシステムやRESTful APIは架空なので存在しません。
ユーザ管理システムにユーザが4人登録されていて、それとは別に外部システムがあるという状態です。これを前提として、GETメソッドとDELETEメソッドを例に解説していきます。
GETメソッドの場合
外部システムくんがユーザ管理システムくんにIDが3番のユーザ情報をくれとリクエストしています。それに対してIDが3番である「さとう あお」の情報を正常というステータスと一緒に、外部システムくんにレスポンスとして返しています。
直感的にわかるかもしれませんが、この操作は1回やっても5回やっても1000回やっても同じ結果になります。
レスポンスは常に同じなのはもちろん、データの取得しかしていないのでデータ状態も同じです。
これは冪等性が保証されているといえます。
DELETEメソッドの場合
外部システムくんがユーザ管理システムくんにIDが4番のユーザ情報を削除してくれとリクエストしています。それに対してIDが4番である「おしお おれんじ」の情報を削除した上で、正常に削除した旨のレスポンスを外部システムくんに返しています。
ではこの操作をもう1回行ったらどうなるでしょうか。
1回目と同様に、外部システムくんがユーザ管理システムくんにIDが4番のユーザ情報を削除してくれとリクエストしています。1回目で削除したので、IDが4番のユーザがいないので、HTTP404(Not Found)というエラーがレスポンスとして返されます。
ではこれは冪等性が保証されているといえるでしょうか。結果が同じといえるでしょうか。
結論をいうと、これは冪等性が保証されています。
なぜかというと、データの状態が1回目も2回目も同じだからです。
どちらもDELETEメソッドが実行されたあとはユーザが3人になっています。
4人だったのが削除されたから3人になったのか、もともと3人だったのかの違いはあれど、ユーザが3人になったという状態は同じです。
つまりレスポンスは関係ないのです。冪等性を保証する上で考えるべきは実行後のデータ状態です。
これがRESTful APIにおける冪等性の肝となります。
まとめ
RESTful APIにおける冪等性で指す「結果が同じ」というのは「レスポンス」ではなく「リソース（データ）」のことである。
ここまで読んでくださっていれば、なんとなくは理解いただけたかと思います。
さいごに
メソッドってなに？とか、HTTPステータス（200,204,404）ってなに？とか気になった方は別途調べてみてください。
というわけで不足分を読者にぶん投げたところでおわりです。
参考サイト
https://qiita.com/sfp_waterwalker/items/765abc2b53cc11d5e367