進化し続けるプロダクトのためのAPI設計

画面ではなくドメインをモデル化する

インターフェースは背後の概念より速く変わる。特定画面の周りに作られたAPIは、提示状態を露出し、新しいクライアントが現れるたびに重複エンドポイントを強いる傾向がある。安定したドメインリソース、そのライフサイクル、ビジネスが認識する操作から始めろ。

理論的純粋さは要らない。プロダクト向けAPIはジャーニーのためにデータを集約できるが、集約には明確な目的と所有が要る。データベース表を直接漏らすな。ストレージ構造はいずれ変わる実装詳細だ。

互換性は機能である

消費者は異なるスケジュールでデプロイする。特にモバイルアプリと外部統合だ。加算的変更は通常より安全だ：新しい任意フィールド、新しいリソース、寛容なリーダー付きの新しい列挙値。既存振る舞いの削除や再定義には、移行計画、テレメトリ、公開された終了日が要る。

セマンティクスが本当に分岐するときバージョニングは有用だが、バージョン番号は互換性の規律を置き換えない。バージョン付きAPIでも、順序・エラー振る舞い・制限・認可の変更で消費者を驚かせうる。機械可読スキーマを保ち、代表的な消費者でテストしろ。

• 未知の列挙値を安全に扱う
• nullabilityとデフォルトを文書化する
• 重要な消費者に契約テストを使う
• 削除前に非推奨フィールドの使用を測る

ミューテーションには身元が要る

信頼できないネットワークではリトライは避けられない。重要なミューテーションでは、呼び出し元と操作にスコープした冪等キーを受け入れろ。結果を保存し、繰り返し要求がアクションを再実行せず元の成果を返すようにしろ。

長時間作業は明示的状態を持つ操作リソースを返すべきだ。クライアントは脆いリクエストを開いたままにせず、ポーリングや購読ができる。サポートも改善する：システムは作業がキュー中・実行中・完了・失敗か、その理由を説明できる。

認可は契約に属する

認証は身元を確立し、認可はその身元がリソース上で操作してよいかを決める。サーバー上で最も狭い意味ある境界で強制しろ。クライアントでボタンを隠すのはインターフェース振る舞いであり、アクセス制御ではない。

マルチテナントシステムは、クライアントが自由に供給して信頼できるテナント文脈を要しない。検証されたメンバーシップからスコープを導き、すべてのリソースアクセスで所有を検証し、監査と調査に十分な文脈で管理アクションをログしろ。

消費者の理解のために最適化する

一貫した命名、予測可能なページネーション、有用なエラー、例、明確な変更ログは、巧妙なプロトコル選択より統合時間を減らす。消費者が内部履歴を学ばずに正しく使えるとき、APIは成功する。

デザインレビューにはクライアントエンジニアと運用シナリオを含めろ。インターフェースは最初の実装より長く生きる。最も変えにくい部分——識別子、セマンティクス、認可、ライフサイクル——に精度を費やせ。