やったこと

• APIデザインパターン 12章 シングルトンサブリソース 読了

学んだこと

ポイント

• データを分離する動機
• シングルトンサブリソースの階層構造
• シングルトンサブリソースに対する標準メソッドの実装
• トレードオフ

学び

• データを分離する動機はいくつか存在する
• シングルトンサブリソースは、常に親リソースを持つ
  • get と updateは、シングルトンサブリソースに対して実施できる
  • createとdeleteは提供しない
    • これらは、親リソースcreateとdeleteに合わせて実施する
• トレードオフ
  • データを、親リソースとシングルトンサブリソースに分割すると、両者を同時に操作することが出来なくなる
  • 上記制約（≒デメリット）と、二つに分けるメリットが、トレードオフとなる

メモ

対象とする問題

あるデータAについて
設計上、リソースのプロパティに設定することが最善。
しかし、いざプロパティに設定すると様々な問題が生じる。

• データ量が多すぎて（または複雑すぎて）帯域幅と計算資源を浪費してしまう
• セキュリティ要件上、分離することが推奨される
• 他のプロパティと、明らかに異なるアクセスパターンを持つ場合
  • 特に、頻繫な更新
  • 書き込み競合が頻繫に発生し、下手をするとデータ消失につながる

そんなケース。
こういった場合は、問題が生じるデータを分離した方が良い。

シングルトンサブリソースの概要

あるリソースの構成要素を、単純なプロパティから、独立したエンティティへ分離すること。
その際、分離したエンティティは、親リソースのプロパティとして機能するのはもちろん、個別のリソースとしても機能できるようにする。

分離したエンティティを、リソースとして定義。
親リソースは、上記定義をプロパティに持つ。

type Car = { //親リソース
  id: string;
  location: Location; // シングルトンサブリソース
}

委譲関係のイメージ。

実装

階層構造

• シングルトンサブリソースは、親リソースを必ず持つ
  • リソース階層のトップに存在してはならない
• シングルトンサブリソースは、他のシングルトンサブリソースを持たない
  • 持たせることもできるが、価値はない

標準メソッド

シングルトンサブリソースに対する標準メソッドは、次の通り。

• get ... シングルトンサブリソースを取得
• update ... シングルトンサブリソースを更新
• create と delete ... シングルトンサブリソースには実装しない

シングルトンサブリソースは、親リソース生成時にのみ、自動生成する。
また、シングルトンサブリソースは、親リソース削除時に、併せて削除する。
そして、シングルトンサブリソースのみcreateとdeleteすることはない。

• 必ず、親リソースへの createとdelete に合わせて、シングルトンサブリソースを createまたはdeleteする

以上より、シングルトンサブリソースを個別に createまたはdeleteするAPIはサポートしない。

シングルトンサブリソースの初期化に際して、値を渡すことは難しい。
そのため、適切な初期値を設定してやる必要がある。
あとは、 updateメソッド経由でシングルトンサブリソースを更新する。

reset メソッド

要件によっては、シングルトンサブリソースが保持するデータを、初期値へ戻したい場合がある。
この場合、上記要件をサポートする reset カスタムメソッドを実装する。

POST /drivers/1/location:reset

トレードオフ

データを、親リソースとシングルトンサブリソースの二つにわけたことで、この二つを同時に（≒アトミックに）操作する手段がなくなる。

同時操作できなくなるデメリットよりも、二つに分けるメリットが大きい場合、シングルトンサブリソースパターンは効果がある。

扱うこと

• シングルトンサブリソースとは
• データをシングルトンサブリソースに分割する理由と、そのタイミング
• 標準メソッドはサブリソースに、どのように作用するか
• シングルトンサブリソースはリソース階層のどこに配置するか

まとめ

• シングルトンサブリソース
  • プロパティとリソースのハイブリッド
  • リソース固有のデータを、分離された別の場所に保存する
  • get,update標準メソッドはサポートする
  • リソースを能動的に作成/削除できてはならない
    • そのため、create,delete標準メソッドはサポートするべきではない
  • リソースの属性を初期状態へ戻す resetメソッドもサポートする必要がある
  • 親リソースにアタッチされるべき
    • そのリソースはそれ自体が別のシングルトンサブリソースであってはならない
• 以下の理由により、データを、リソースからシングルトンサブリソースへ分割する
  • サイズ
  • 複雑さ
  • 個別のセキュリティ要件
  • 異なるアクセスパターンとその結果生じるボラティリティ