API のスキーマが適切に設計され、他の API との整合性があるか？¶
Type: Structure
Category: API・権限・セキュリティ
Audience: 設計初心者 / 設計中のチーム / レビュワー
背景・概要¶
APIスキーマは他チーム・他システムとの契約であり後から変更しづらい、整合性の乱れは連鎖的な障害や運用コストの増大を招く
特に共通的なエンティティの表現（User, Taskなど）に関しては、プロジェクト横断で整合性を保つことが重要
例¶
- 共通項目（id, status, created_at）の命名・型を統一
- 内部のEnum/値オブジェクトの表現をAPIでも可能な限り一致させる
- 適切にネストされた構造体や、REST風のURL設計（/users/{id}/tasks）をする。後者はgRPCで不要になるかも
よくある失敗例¶
- 同じ意味のフィールドuser_uuidとuidなどが混在
- スキーマが内製的すぎてAPI利用者が実装を読まないと理解できない
- 外部向けAPIに内部設計がそのままが露出していて、リファクタが困難
FAQ¶
Q. 内部モデルとAPIスキーマの設計は分けるべき？
A. 基本的には分けるべき。ただし外部入出力用のDTOを設けて必要に応じてアダプター層を用意してマッピングするとよい
Q. 他チームのAPIと整合性がとれていない場合は？
A. 必要に応じてAdapterパターンやMapper/TranslatorなどによるDTO <–> Domainの変換器で吸収すればよいが、長期的には統一を検討すべき