【えーぴーあいこんとらくと】

APIコントラクトとは？

最終更新: 2026年10月2日

💡 APIの提供者と利用者が共有する約束

APIの提供者と利用者が共有する、要求・応答や認証・エラーなどの約束。OpenAPIやGraphQLスキーマによる記述、仕様先行の開発、実装との整合性確認と互換性の限界を解説します。

📌 このページのポイント

線は同じ仕様を参照する関係で、通信の経路ではありません。OpenAPI等で記述でき、コントラクトテストにも検証範囲があります。

ひよこ

APIコントラクトには、何を書くの？

ペンギン先生

どの操作を呼べるか、どんな入力を送り、どんな結果が返るかを決めるよ。HTTP APIならパス・メソッド・パラメーター・応答形式・ステータスコードなどだ。認証やエラーの扱い、項目の意味もそろえると、利用者との認識違いを減らせる。

ひよこ

OpenAPIが、コントラクトそのもの？

ペンギン先生

HTTP APIを機械でも読める形で説明する標準の1つだよ。JSONやYAMLで記述でき、対応するツールで文書やコードなどを生成できる。すべてのAPIがOpenAPIを使うわけではなく、GraphQLではスキーマで型や操作を表すんだ。

ひよこ

最初に決めると、どう便利なの？

ペンギン先生

仕様をレビューして合意し、それに基づくモックを用意すると、利用側と提供側が並行して作業しやすくなる。コントラクトファーストと呼ばれる進め方だよ。ただし、実装中に変える必要が出たら双方へ伝え、仕様と実装を一緒に更新しよう。

ひよこ

仕様どおりの型なら、変更しても平気？

ペンギン先生

必ずではないよ。同じ数値型でも、金額の単位が円から銭に変われば利用側の計算が壊れることがある。項目の削除や必須入力の追加だけでなく、意味やエラーの動作の変化も確認するんだ。

ひよこ

コントラクトテストで、全部保証できる？

ペンギン先生

たとえばPactは利用側が期待する要求・応答を記録し、提供側でも確認する仕組みだよ。ただし確認したやり取りが対象で、業務ロジック全体や性能の試験を置き換えるものではない。仕様の検査、機能の試験、運用時の確認を組み合わせよう。

もっと詳しく知りたい人へ

OpenAPIとSwaggerは同じ名前？

OpenAPIは仕様の名前です。Swaggerは、その仕様に関連するツールなどの名前としても使われます。古いSwagger仕様からOpenAPIへ発展した経緯はありますが、現在の仕様とツールをすべて同じものとして扱わないようにします。

新旧のAPIを分ける方法はありますが、利用者が移行する手順、旧版を維持する期間、認証やデータの互換性なども必要です。URLに番号を付けるだけで既存の利用者が安全に移行できるわけではありません。変更が利用者へ与える影響を調べ、合意した移行計画とテストで確認します。

まとめ：ざっくりこれだけ覚えればOK！

「APIコントラクト」って出てきたら「APIをどう呼び、何が返るかを共有する約束」と思えばだいたいOK！

📖 おまけ：英語の意味

「API Contract」＝ APIの契約・約束

💬 提供者と利用者の間で共有する仕様を、契約になぞらえています。ここでいう契約は、法的な契約書だけを指すものではありません。