用語集 › 💻 プログラミング › APIコントラクト
【えーぴーあいこんとらくと】

APIコントラクト とは？

💡 APIの約束事を文書化、フロントとバックの契約書
📌 このページのポイント
APIコントラクト — プロバイダとコンシューマの約束 プロバイダ （API提供側） サーバー コンシューマ （API利用側） クライアント APIコントラクト ・エンドポイント ・リクエスト形式 ・レスポンス形式 ・ステータスコード 形式の例 OpenAPI / Swagger GraphQL Schema 契約で決まること URL・メソッド・型 エラー形式・認証方式 メリット 並行開発が可能 破壊的変更を防止 双方が契約に従うことで、独立して開発・テストできる
APIコントラクト — プロバイダとコンシューマの約束
ひよこ ひよこ

APIコントラクトって何で必要なの？

ペンギン先生 ペンギン先生

フロントエンドとバックエンドが別チームで開発するとき、APIの仕様が曖昧だと待ちが発生したり認識ズレが起きるよね。コントラクトを先に決めておけば並行開発できるんだ

ひよこ ひよこ

OpenAPIって聞いたことあるけど、それがコントラクト？

ペンギン先生 ペンギン先生

そうだよ。OpenAPI（旧Swagger）はREST APIのコントラクトを記述する標準フォーマットで、YAML/JSONで書く。そこからドキュメント生成、モックサーバー、クライアントコードの自動生成もできるんだ

ひよこ ひよこ

コントラクトが変わったらどうするの？

ペンギン先生 ペンギン先生

バージョニングが大事だね。破壊的変更はv2としてエンドポイントを分けるか、APIの進化的設計として後方互換性を保つのが基本。コントラクトテストで既存クライアントが壊れないことを自動検証する仕組みも大切だよ

ひよこ ひよこ

コントラクトファーストって実際どうやるの？

ペンギン先生 ペンギン先生

まずOpenAPIやGraphQLスキーマを書いて関係者でレビューする。合意が取れたらそこからモックサーバーを立てて、フロントはモック相手に開発を進める。PactというツールでConsumer-Driven Contract Testingを行うと、マイクロサービス間の互換性も保証できるよ

ペンギン
まとめ：ざっくりこれだけ覚えればOK！
「APIコントラクト」って出てきたら「APIの仕様を明文化した契約書」と思えればだいたいOK！
📖 おまけ：英語の意味
「API Contract」 ＝ APIの契約
💬 Contract は「契約」という意味で、APIの提供者と利用者の間の約束事ということだよ
🔗 あわせて読みたい
← 用語集にもどる