ルール
避ける 破る public API 契約を
変更 変更 public API エンドポイント 変更 既存の
既存の クライアント リクエスト である 変更 変更を
考えてみてください 考えて API API 契約 を a プロミス — 変化する
それを 変更する クライアント 依存 に それ 休憩 彼らの コードを
サポート言語: PHP、 Java、 C#、 Python、 JavaScript、 TypeScriptはじめに
Public APIは、サービスとそのコンシューマー間の契約です。クライアントがエンドポイントのリクエスト形式、レスポンス構造、または動作に依存するようになると、それを変更するとクライアントのコードが破損します。破壊的変更はすべてのクライアントに同時更新を強制しますが、クライアントを制御できない場合は多くの場合不可能です。モバイルアプリは強制的に更新できず、サードパーティの統合には移行時間が必要であり、レガシーシステムは更新されない可能性があります。
なぜ重要なのか
クライアントの中断と信頼: 破壊的なAPI変更は、本番クライアントアプリケーションで即座に障害を引き起こします。ユーザーはエラー、データ損失、または完全なサービス停止を経験します。これはAPIプロバイダーとコンシューマー間の信頼を損ない、安定したAPIは安定したままであるという暗黙の契約に違反します。
調整コスト: 複数のクライアントチーム間で破壊的変更を調整することは、コストがかかり、時間がかかります。各チームは、コードの更新、変更のテスト、デプロイに時間を要します。未知のクライアント（モバイルアプリ、サードパーティ統合など）を持つ公開APIの場合、調整は不可能です。
バージョンの乱立: 不適切に管理された破壊的変更は、複数のAPIバージョンを同時に維持することにつながります。各バージョンには個別のコードパス、テスト、ドキュメント、バグ修正が必要であり、メンテナンスの負担が指数関数的に増加します。
コード例
❌ 非準拠：
// Version 1: Original API
app.get('/api/users/:id', async (req, res) => {
const user = await db.users.findById(req.params.id);
res.json({ id: user.id, name: user.name });
});
// Version 2: Breaking change - renamed field
app.get('/api/users/:id', async (req, res) => {
const user = await db.users.findById(req.params.id);
res.json({
id: user.id,
fullName: user.name // Breaking: 'name' renamed to 'fullName'
});
});
誤っている理由： name を fullName に変更すると、name フィールドを期待している既存のすべてのクライアントが動作しなくなります。response.name にアクセスするクライアントコードは undefined を受け取り、エラーを引き起こします。この変更により、すべてのクライアントが同時に更新するか、失敗するかのどちらかを強いられます。
✅ 準拠済み:
// Version 2: Additive change - keeps old field, adds new
app.get('/api/users/:id', async (req, res) => {
const user = await db.users.findById(req.params.id);
res.json({
id: user.id,
name: user.name, // Keep for backward compatibility
fullName: user.name // Add new field (deprecated 'name')
});
});
// Or use API versioning
app.get('/api/v2/users/:id', async (req, res) => {
const user = await db.users.findById(req.params.id);
res.json({ id: user.id, fullName: user.name });
});
これが重要である理由： 古いものを維持する 名前 このフィールドは、機能を追加しながら下位互換性を維持します 氏名 新しいクライアント向け。あるいは、新しいバージョン管理されたエンドポイントを作成する（/api/v2/）は、まだ使用している既存のクライアントに影響を与えることなく、破壊的な変更を許可します /api/v1/.
まとめ
追加的な変更を通じてAPIを進化させます。新しいフィールドの追加、新しいエンドポイントの追加、オプションパラメーターの追加などです。破壊的変更が避けられない場合は、APIバージョニングを使用して古いバージョンと新しいバージョンを同時に実行します。古いフィールドは、明確なタイムラインと移行ガイドを提示した上で非推奨とし、その後削除します。
