API設計:具体的アプローチと抽象的アプローチ-ベストプラクティス?
システム間で(ビジネスレベルで)APIについて議論するとき、チームには2つの異なる視点があります。一般的な抽象アプローチを好む人もいれば、そうでない人もいます。 例:単純な「個人検索」APIの設計。具体的なバージョンは searchPerson(String name, boolean soundEx, String firstName, boolean soundEx, String dateOfBirth) 具体的なバージョンを支持する人々は言う: APIは自己文書化されています わかりやすい 検証は簡単です(コンパイラーまたはWebサービスとして:スキーマ検証) キッス 私たちのチームの他のグループは、「これは単なる検索条件のリストです」と言うでしょう。 searchPerson(List<SearchCriteria> criteria) と SearchCritera { String parameter, String value, Map<String, String> options } おそらくいくつかの列挙型の「パラメータ」を作成します。 支持者は言う: API(の宣言)を変更することなく、実装は変更できます。たとえば、基準やオプションを追加します。展開時にそのような変更を同期しなくても。 具体的なバリアントでもドキュメントが必要です スキーマ検証は過大評価されており、多くの場合、さらに検証する必要があります。スキーマはすべてのケースを処理できません 別のシステムと同様のAPIが既にあります-再利用 反論は 有効なパラメーターと有効なパラメーターの組み合わせに関する多くのドキュメント 他のチームにとって理解するのがより難しいので、より多くのコミュニケーション努力 ベストプラクティスはありますか?文献?