更新系 Web API response 再考
更新系の Web API response をどうすればいいのか毎回悩むので良い感じのデザインパターンをパッと調べたけど見当たらなかったので友達と議論した。
どんな場合はどんな response を返すべき、という結論には至らなかったけど一通りのパターンは洗い出せたと思うのでメモしておく。
TL;DR
- response bodyを返さないパターン
- 更新したリソースの id だけ返すパターン
- 更新したリソース全体を返すパターン
- 更新したリソースだけを返すパターン
- 関連する情報を含む更新したリソースだけを返すパターン
- 更新したリソースのうちクライアント側が必要な情報だけを返すパターン
response bodyを返さないパターン
204 を返すパターン。 protocol buffer だと google.protobuf.Empty を返すパターン。
リソースの新規作成など、response として property を返さなくてもクライアント側でリソースの状態を知る術がある場合に使う印象がある。
更新したリソースの id だけ返すパターン
response body を返さないパターンと使う場面は大きく変わらない気がしている。
しかし、クライアント側が更新したリソースの id を知る術がない（request で複数のパラメータによってリソースを一意に特定するといった id 以外の情報で指定している場合）がクライアントが id を key として状態を管理しているため id を知りたい、といったケースでは id だけ返すパターンの有用性が出てくる。
更新したリソース全体を返すパターン
これは backend 側の目線で返すリソースを決めるパターンで大別すると2つに分類できる。
- 更新したリソースだけを返すパターン
- 関連する情報を含む更新したリソースだけを返すパターン
どっちで返すかはパフォーマンス次第という印象がある。
更新したリソースのうちクライアント側が必要な情報だけを返すパターン
これは frontend 側の目線で返すリソースを決めるパターンで実装方針は2つに分類できる。
柔軟なinterfaceである程度endpointを共通化するパターン
サーバに対してクライアントが複数存在しユースケースがたくさんある場合、こっちの方が手早く開発できる印象がある。 GraphQL, Protocol Buffer の Field Mask, Rails active-model-serializer の fields パラメータなどはこれに該当する。
固定のinterfaceで必要な情報のユースケース分のendpointを作るパターン
サーバとクライアントが 1:1 対応しているような比較的小規模なアプリケーションではこっちの方が手早く開発できる印象がある。
