REST APIの特殊な場合その2

以前、「REST APIの特殊な場合のエンドポイント集」と題していくつかの案を載せましたが、今回はその続きです。

テーマは「論理削除と物理削除」です。

基本は論理削除

例えばユーザーを削除するAPIのエンドポイントはDELETE /users/:userIdです。管理者権限を持っていないと削除できない場合は、先日の記事に従うとDELETE /administrators/~/users/:userIdです。

では、このAPIで削除した場合は論理削除にすべきでしょうか？物理削除にすべきでしょうか？

見出しでネタバレしていますが、論理削除にしましょう。いきなり物理削除してしまうと、間違えて削除してしまった場合に「元に戻す」などの機能を実装できません。常に人間はミスをするという前提でAPIを設計しましょう。

論理削除したリソースの操作

では、論理削除されたユーザーの操作、例えば一覧を取得や復元などはどのようなエンドポイントにすればいいでしょうか。

ここで、先日の記事の「特殊な絞り込みは、先頭に@を使う」を使います。

例えば、論理削除されたユーザーの一覧を取得したい場合はGET /users/@trashed、特定のユーザーの情報を取得したい場合はGET /users/:userId/@trashedのように@trashedをつけることで「論理削除による絞り込み」を表現します。

復元

論理削除されたユーザーの復元APIは、例えばPUT /users/:userId/@trashedでしょうか。リクエストボディーは不要で、そのままPUTリクエストを投げれば復元してくれるような設計だと便利かもしれません。

これだと論理削除されたユーザーの情報を編集するAPIも同じエンドポイントになってしまいますが、そこは「論理削除されたユーザー情報は編集できない（編集したい場合は一度復元する必要がある）」と割り切ってしまいましょう。

物理削除（完全削除）

リソースは原則として物理削除すべきではないかもしれませんが、そうは言っても論理削除ばかりしていると使いもしないデータが溜まってDBが肥大化したり、有効なリソース数は少ないのにやたらクエリーに時間がかかったりします。あるいは、ユーザーIDのようにユーザー自身が決める一意の情報がいつまで経っても解放されず、新規登録者が同じIDを使いたい場合に支障が出てしまいます。

・・・というように、運用上は物理削除してしまいたい場合もあるので、そのためのAPIも用意しましょう。

もうおわかりですね。DELETE /users/:userId/@trashedです。一度論理削除したリソースをあらためて物理削除するイメージです。

なお、リソースを物理削除すると関連情報も連鎖的に削除される場合は、どのリソースが連鎖削除されるのかをAPIドキュメントに明記しておきましょう。たとえば、ユーザーを物理削除すると、そのユーザーの投稿データ（ツイート等）も物理削除される等です。

いきなり物理削除はしない

物理削除APIがDELETE /users/:userId/@trashedだと、一度論理削除しないと物理削除できません。最初から物理削除したい場合はどうすればいいのかという疑問が出るかもしれませんが、そこはいきなり物理削除はしない、つまり「必ず論理削除後に物理削除する」という仕様にしてしまいましょう。

最初に書いたとおり、人間はミスをするものです。いきなり物理削除してしまうと間違えて削除してしまった場合に取り返しが付きません。

どうしても最初から物理削除をしたいというような場合は、DELETE /users/:userId?purge=1のようにクエリーストリングでいきなり物理削除するオプションをつける方法もありますが、正直おすすめしません。クライアントに人質をとられて脅されているというような場合以外では実装しないほうが賢明です。