やったこと

• API デザインパターン 16章 ポリモーフィズム 読了

学んだこと

ポイント

• ポリモーフィックリソースとポリモーフィックメソッド
• ポリモーフィックメソッドを使用するべきではない理由
• どのような時にポリモーフィックリソースを使用するべきか
• ポリモーフィックリソースの構造

学び

• ポリモーフィックリソース
• ポリモーフィックメソッド
  • こちらは使用するべきではない
• ポリモーフィックリソースを使用するべきタイミング
  • 汎用的な型を扱うことが合理的な場合
    • オブジェクト指向で I/Fを扱う時と同じ動機

• ポリモーフィックリソースは、 typeフィールドで、具体的な型情報を管理する

  • データ部分のチェックも大事 ## 気づき

• ポリモーフィックリソースを使用するべきかの判断は、オブジェクト指向にて「I/F型と具象クラスの型、どちらを宣言するか」と同じ基準

  • 設計者の意図を反映できる
  • 読み手は、APIの型から、設計者の意図をくみ取ることが出来る

メモ

オブジェクト指向の文脈で登場する「ポリモーフィズム」を、リソース指向APIの世界に持ち込む。
そのための方法やガイドラインを見ていく。

概要

ポリモーフィックリソース ... 汎用的な型でありつつ、具体的な型情報をもつリソースのこと。
これにより、汎用的な型用の処理を使いまわすことが出来る。

• 言い換えると、具体的な型一つ一つに、専用のメソッドを作成する必要がなくなる

実装

ポリモーフィックリソースを使用するべきタイミング

汎用的な型（Messageなど）を扱いたい場合は、ポリモーフィックリソースを使用する。

• この場合、全メッセージの一覧を取得するAPIなど

具体的な型（Messageに対して、 VideoMessageなど）を扱いたい場合、具体的な型専用のリソースを扱うことになる。

考え方は、オブジェクト指向で「I/F型と具象クラスの型、どちらを宣言するか」と同じ感じ。

構造

ポリモーフィックリソースは、具体的な型情報を保持する type フィールドを持つ。

ポリモーフィックリソースを扱う側は、 type フィールドを参照することで、リソースの具体的な型情報を知ることができる。

具体的な型の個別フィールド

具体的な型の個別フィールドは、content などの共通フィールドに集約させる。
リソースを扱う側は、 typeフィールドの値を確認することで、 共通フィールドが保持する値を特定できる。

ポリモーフィックリソースによる抽象化は、データ構造が実用的な意味を失わない範囲にとどめる。

• Messageの例だと、 Messageオブジェクトの責務（メッセージ情報の取り扱い）を逸脱しない範囲で抽象化すること

データのチェック

• type の値に応じて、共通フィールドの値をチェックし、必要ならエラーを返す
  • type がMessage の content : string は、ただの文字列である可能性
  • typeがPhotoMessageのcontent : stringにて、contentにURIが期待されている場合、URIの構造に則った文字列であることをチェックする
• 余分なデータが渡されてきた場合、余分なデータは破棄し、処理を続行する

ポリモーフィックな振る舞い

ポリモーフィックメソッド ... リソースの typeに応じて、振る舞いを変えるメソッド。

結論として、ポリモーフィックメソッドを使用するべきではない。

メソッドは、似たような名前でも、扱うリソースに応じて、振る舞いは微妙に異なる。
これらを無視して共通化すると、APIの変更が困難になる ... というトラブルが発生する。

• あるリソースだけ検証リクエストを挟もうとしても、共通化しているため、全リソースに対して検証リクエストを飛ばしてしまう
• ちょっと処理を変更すると、あるリソースにとっては最適解となっても、他のリソースではエラーが発生する
• など

そのため、ポリモーフィックメソッドに変更を加える場合、ポリモーフィックメソッドで取り扱う全リソースの振る舞いを、一斉に変更する必要がある。

以上より、ポリモーフィックメソッドは使用するべきではない。

トレードオフ

ポリモーフィックリソースは非常に強力なツールだが、APIに複雑さを持ち込む。

• 特に、リソースの表現方法が固定されてしまい、将来変更することが難しくなる

そして、ポリモーフィックメソッドは、使用するべきではない。

---

扱うこと

• ポリモーフィズムとは何か
• 利点は何か、APIではいつ利用するべきか
• ポリモーフィックリソースの構成方法
• リソース指向APIにおいてポリモーフィックメソッドを避けるべきる裕

まとめ

• APIにおけるポリモーフィズムは、リソースが様々な型を取ることを可能にし、共有機能の重複を避けることが出来る
• API利用者が複数の種類のリソースを同時に取得するケースがある場合、ポリモーフィズムは有効
  • 様々な型の Message オブジェクトをまとめて取得したい場合 ... など
• ポリモーフィックリソースの型情報は文字列フィールドであるべき
  • リソースの変更、追加、削除は、既存のクライアントへの影響を十分に考慮すること
• 無効な入力データに対しては、必要なデータが存在するかどうかチェックし、無関係なデータは無視する
  • 無関係なデータを確認しても、エラーを投げるべきではない
• ポリモーフィックメソッドは硬直化する（≒変更が非常に困難）ため、利用は極力避ける