やったこと

• APIデザインパターン 13章 相互参照 読了

学んだこと

ポイント

• 参照先を識別するフィールドの名前
• 参照先が削除済みの場合を考える
• 参照と値、両者の特徴

学び

• 参照先を識別するフィールド
  • 文字列型を使用する
  • サフィックス（末尾）をIDとし、名前で識別子であることを表現する
• 参照先が削除済みの場合、取れる選択肢は3つほど考えられる
  • いずれもトレードオフがある
• 参照と値は、どちらも利点/欠点が存在する
  • 要件に合わせて、どちらを使用するか検討する
  • GraphQLの導入は、より良い解決策の一つ

メモ

取り扱う問題

リソースは、同じAPIや、外部APIが保持する「他のリソース」を指すことが出来る。
この「他のリソース」を参照する方法は実装者の判断に委ねられる。

• 例）「他のリソース」を削除できるのか？
  • 削除できる場合、削除した時、「他のリソース」の参照元はどう振る舞うべきか？
    • 後処理が必要？
    • そのままでOK？

そのため、リソースを参照するガイドラインと、その参照を支える動作パターンの定義が必要になる。

相互参照パターンの概要

文字列型の一意な識別子を使用して、「他のリソース」を識別し、参照できるようにする。
相互参照パターンによって、参照元と「他のリソース」を分離できる。
これは、柔軟なAPI設計を実現できる一方で、識別子情報が古く（例: 参照先である「他のリソース」が削除された場合など）なり、識別子が無効となることを考慮しなければならない。

実装

参照フィールドの名前

サフィックス（末尾）に IDと付与し、識別子であることを名前で表現する。

データの整合性

参照先のリソースを削除する（または既に削除されている）場合、参照元のリソースは、以下の選択肢を取ることが出来る。

1. そもそも参照先のリソース削除を禁止する
2. 参照先のリソースは削除できるが、識別子情報にゼロ値を設定する
3. 参照先のリソースを削除し、実行時に無効な識別子を処理する

1と2は、API提供側で何とかする方法。
更新するデータが膨大になると処理が遅くなったり、ポインタの循環参照が発生する恐れがある。

3は、API利用者側で例外処理をお願いする方法。
API利用者側に不便を強いるが、一貫性のある振る舞いを提供できる。

値か参照か

参照を用いると、参照先のデータが常に最新であることを保証できるが、別途データの取得処理を実行する必要がある。

• つまり、参照元のデータと参照先のデータを取得する、計二回の処理が必要

値を用いると、データ取得処理は一回でよいが、以下の問題を考える必要がある。

• 値が古くなっている可能性の考慮が必要
• 値が持つデータが増えると、それだけ一つのレスポンスが膨大になる
• API利用者が参照元リソースを更新できる場合、混乱する恐れがある
  • 参照先リソースを更新するには、どうすればよい？

より良い解決策は、参照を単独で使用し、GraphQLで参照をつなぎ合わせること。
これにより、一つのクエリで必要なリソースの最新情報を取得できる。

---

扱うこと

• リソースを参照するフィールド名にふさわしい名前
• 参照フィールドは参照整合性の問題をどのように扱うべきか
• フィールドがリソースのコピーを保持するべきタイミングとその理由

まとめ

• 参照を格納するフィールドは、識別子の種類が何であれ、文字列型とし、サフィックスを"ID"とする
  • hogehogeIdなど
• 一般的に、参照先のリソースの存続期間にわたって参照が維持されることを期待すべきではない
  • つまり、「参照先のリソースが削除され、参照が無効になること」を考慮するべき
• リソースデータは参照しているリソースにインラインで保持されていることがある
  • 参照データと比較して、インラインデータは更新作業が必要
  • 更新しない場合、データが古くなる可能性がある