男女比はカレーと福神漬けと同じくらい

マサカリよろしくお願いします。

更新系 Web API response 再考

更新系の Web API response をどうすればいいのか毎回悩むので良い感じのデザインパターンをパッと調べたけど見当たらなかったので友達と議論した。

どんな場合はどんな response を返すべき、という結論には至らなかったけど一通りのパターンは洗い出せたと思うのでメモしておく。

TL;DR

  • response bodyを返さないパターン
  • 更新したリソースの id だけ返すパターン
  • 更新したリソース全体を返すパターン
    • 更新したリソースだけを返すパターン
    • 関連する情報を含む更新したリソースだけを返すパターン
  • 更新したリソースのうちクライアント側が必要な情報だけを返すパターン
    • 柔軟なinterfaceである程度endpointを共通化するパターン
    • 固定のinterfaceで必要な情報のユースケース分のendpointを作るパターン

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を共通化するパターン
  • 固定のinterfaceで必要な情報のユースケース分のendpointを作るパターン

柔軟なinterfaceである程度endpointを共通化するパターン

サーバに対してクライアントが複数存在しユースケースがたくさんある場合、こっちの方が手早く開発できる印象がある。 GraphQL, Protocol Buffer の Field Mask, Rails active-model-serializer の fields パラメータなどはこれに該当する。

固定のinterfaceで必要な情報のユースケース分のendpointを作るパターン

サーバとクライアントが 1:1 対応しているような比較的小規模なアプリケーションではこっちの方が手早く開発できる印象がある。

Thanks to