やったこと

• API デザインパターン 25章 論理削除 読了

学んだこと

ポイント

• 論理削除とは
• 論理削除の実装方法
• 論理削除実装の際に考えるべきこと

学び

• 論理削除とは、後から復元可能な削除方法
• 以下の方法で実装する
  • 論理削除フラグを使って、削除状態を制御
  • リソースのステータスに 削除ステータスを追加する
  • 論理削除は標準の delete メソッドで実装。ほかにも、以下を実装する
    • 復元用の、undelete カスタムメソッド
    • 物理削除用の expunge カスタムメソッド
• 論理削除実装の際は、期限切れや参照整合性など、いくつか追加で考えることがある
• 標準の delete メソッドに適用される参照整合性ガイドラインは、論理削除されたリソースにも同様に適用する

気づき

メモ

標準の delete メソッドの目的は、リソースを削除する事。
この時、 物理削除だけではなく、ゴミ箱のように復元できるような削除方法も選択できる。
復元できるような削除方法である「論理削除」について見ていく。

対象とする問題

ユーザーは、何らかの理由で削除を取り消したい場合がある。

• フィルタリングのミス
• （APIの削除リクエストを叩くような）スクリプトのミス

こういった状況を想定し、復元できる手段を残す。

概要

論理削除を実装する主な手段は以下の通り。

• 論理削除を示す deleted フラグ
• 既存のリソース状態を示すパラメータに、 deleted を追加する

実装

論理削除は、標準の delete メソッドに実装することになる。
論理削除実装に伴い、以下も必要となる。

• 物理削除用の expunge カスタムメソッド
• 復元用の undelete メソッド
• 他の標準メソッドの動作を変更
  • 例
    • 標準の list メソッドにて、 論理削除されたリソースを除外する

削除済みの指定方法

1. boolean型のフラグを使用する方法
   • デフォルトは false
2. 状態フィールド
   • リソースの状態を示すプロパティに、論理削除ステータスを追加する方法
   • 論理削除を取り消すとき、どの状態へ遷移させるかが問題となる

標準メソッド修正する

論理削除の実装に合わせて、必要に応じて、標準メソッドを変更する。

GET

論理削除情報も含め、通常通りリソースを返却する。

• つまり、論理削除されたリソースへの GET で 404 を返してはならない
• 「IDを指定して論理削除されたリソースの GET をリクエストする」のは、リソースの削除状態を確認するという目的と考えられるため

LIST

デフォルトでは、論理削除されたリソースは除外して、リソース群を返却する。
論理削除されたリソースも含めたリソース群を要求できるようにしたい場合、リクエストインターフェースを拡張することになる。
includeDeleted フラグなど。

フィルタリングで実装しないこと。

• 全ての LIST がフィルタリングをサポートしているわけではない
• フィルタリングは、結果として、常にデータを減らすことになる
  • includeDeletedフラグは、反対にデータを増やすことになる

API の目的に一貫性と明確さを保つ意味合いもある。

DELETE

論理削除に合わせて、 フラグを変更する処理に変更する。
論理削除済みのリソースに対して
DELETE を要求された場合は、命令型と宣言型（7章）のどちらを取るかという、APIの一貫性に従う。

• 一般的には、期待通りにリクエストを実行できなかったことを示す、412エラーとする

復元する

undelete カスタムメソッドを用意し、論理削除フラグを変更する。
未削除のリソースに対して undelete を要求された場合は、命令型と宣言型（7章）のどちらを取るかという、APIの一貫性に従う。

• 一般的には、期待通りにリクエストを実行できなかったことを示す、412 エラーとする

物理削除する

expurge カスタムメソッドを用意し、物理削除を実装する。

未削除のリソースに対して expurge を要求された場合、 削除フラグの如何に関わらず削除してしまう。

期限切れ

定期的にゴミ箱を空にしたい場合などに使用する。

論理削除をサポートするリソースに、有効期限を表すフィールドを設ける。
論理削除状態以外の状態のとき、有効期限を表すフィールドはNullになる。

参照整合性

論理削除されたリソースは、他のリソースから参照可能かどうか、決めておく必要がある。
正解はなく、他のAPIと同じルールを適用することが重要。

• 参照整合性を保つために削除を禁止しているのであれば、同じ制約を論理削除にも課す ... など

バージョンを介した論理削除の追加

後から、論理削除機能を追加する場合、どうやって安全に機能を追加するか。

結論は、正解はなく、状況による。

後方互換性が無いと判断される可能性を考慮し、論理削除実装の際はメジャーバージョンのアップを考慮しておくと良い。

---

扱うこと

• 倫理削除とは？それがいつ有効か？
• リソースに削除マークを付け、実際には削除されていないことを示す方法
• 論理削除をサポートするリソースの標準メソッドに必要な修正
• 論理削除されたリソースの削除を取り消す方法
• 削除されたリソースを永久に削除（物理削除）する方法
• 参照整合性の管理

まとめ

• 論理削除とは、リソースを削除済みとしてマークする機能
  • deleted フラグで表現することが多い
  • 既にリソースの状態を表すパラメータを導入しているのなら、そこに deleted を追加するのも有り
• 論理削除をサポートする標準メソッドは、いくつかの小さな変更が必要
  • 論理削除されたリソースに対して get をリクエストした場合、404を返してはならない
• 論理削除されたリソースには、復元用の undelete カスタムメソッド、 物理削除用の expunge カスタムメソッドを提供する
• 標準の delete メソッドに適用される参照整合性ガイドラインは、論理削除されたリソースにも同様に適用しなくてはならない
  • 参照されるリソースのカスケード削除など
  • 一貫性を維持するため