必須項目に「いずれか必須」があるAPI設計の罠
必須項目に「いずれか必須」があるAPI設計の罠
APIの設計において「必須項目」という概念は非常に重要です。
リクエストにおいて、必須項目が満たされていない場合、サーバー側で適切に処理を行えないためエラーを返すのは当然のことです。
しかしながら、仕様書や設計において時折目にする「いずれか必須」という表現は、API設計の落とし穴を露呈しているケースと言えます。
「いずれか必須」とは？
「いずれか必須」とは、複数のパラメータの中で少なくとも1つが指定されていれば良いという仕様です。例えば：
- パラメータA: △ 必須
- パラメータB: △ 必須
（どちらか一方を必須とする）
一見すると柔軟な仕様のように見えますが、これには設計上の課題が潜んでいます。
「いずれか必須」がもたらす問題
1. 曖昧で理解しにくい仕様
「いずれか必須」は直感的ではありません。
APIの使用者にとって、どの組み合わせが有効かを正確に理解するには仕様書を何度も読み込む必要があります。
また、テストケースを考える際も複雑になります。
2. バリデーションが煩雑
リクエストを処理する際に「どの条件が満たされていればOKか」を判定するロジックが必要になります。
特定のパラメータがある場合とない場合で、異なる処理フローを実装することになり、コードが複雑化します。
3. メンテナンス性が低下
「いずれか必須」の条件にさらに新しいパラメータが追加されたり、既存の条件が変更された場合、仕様変更が難しくなります。
全体のユースケースに影響が及ぶため、既存の利用者への影響を考慮する必要が出てきます。
4. APIの目的が曖昧になる
そもそも「いずれか必須」とするのは、1つのAPIで複数のユースケースを処理しようとしていることが原因です。
これにより、APIが何を目的としているのかが不明確になります。
解決策: APIを分けるべき理由
1. 単一責任の原則
APIはそれぞれ明確な責任を持つべきです。
1つのAPIが複数のユースケースを処理しようとするのではなく、ユースケースごとに分割することで、設計がスリムになり、利用者も混乱しません。
2. 明確な仕様
APIを分けることで、それぞれのAPIで何が必須で何が任意かが明確になります。
「いずれか必須」といった曖昧な表現を排除し、仕様をより直感的に理解できるようになります。
3. メンテナンス性と拡張性の向上
ユースケースごとにAPIを分けると、それぞれのAPIが独立しているため、新しいユースケースやパラメータの追加が容易になります。
また、既存のAPI利用者に影響を与えるリスクも軽減されます。
4. テストが簡単になる
分割されたAPIはそれぞれ単純な構造になるため、テストケースの設計も簡素化します。
「柔軟なAPI」からの脱却
「いずれか必須」という仕様は一見柔軟なAPIに見えるかもしれませんが、実際には設計を複雑化し、利用者や開発者にとって混乱を招きます。
API設計においては、「単一責任」と「明確な仕様」を重視し、ユースケースに応じて適切にAPIを分けることが、長期的な成功につながるのです。
Discussion