AI駆動開発とAPIはなぜ相性が良いのか
先に結論
AIとAPIの相性が良い理由は、APIが新しいからでも、HTTPがAI向けだからでもない。入力、出力、型、必須項目、認証方式、失敗条件を、OpenAPIなどの機械可読な契約として表せるからである。
自然言語の要求だけをAIへ渡すと、AIは不足した前提を補いながらもっともらしい実装を作る。契約を渡すと、生成できる範囲と検証すべき範囲を狭められる。重要なのはAIにコードを書かせることではなく、人間とAIが同じ境界を読み、差分をテストできる状態を作ることなのだ。
少し難しく聞こえるが、考え方は注文票に近い。口頭で「いつもの感じで届けて」と頼めば、相手は不足した情報を推測するしかない。商品名、数量、届け先、希望時刻、支払方法を決められた欄へ書けば、受け取る側は迷いにくく、記入漏れも見つけやすい。API契約は、システム同士のやり取りに使う注文票のようなものなのだ。
APIは、あるシステムの機能を別のシステムから利用するための窓口である。たとえばスマートフォンの買い物アプリが「商品一覧を取得する」「注文を登録する」「配送状況を確認する」とき、画面の裏側ではAPIを通じてサーバーへ依頼していることが多い。OpenAPIは、その窓口ごとに何を送ればよいか、どのような返事が来るかを記述するための標準仕様である。
本稿はプログラムの書き方を説明する記事ではない。非技術者には、AIへ曖昧な依頼を渡すことの危険と、契約を先に整える意味をつかんでもらう。技術初学者には、OpenAPI、Schema、テストがどうつながるかを、一つの会員情報更新APIを例に追ってもらうのだ。
| 層 | 機械可読にするもの | AIに任せられること | 人間が決めること |
|---|---|---|---|
| 要求 | ユースケース、受入条件、禁止事項 | 不足条件の抽出、仕様案の生成 | 業務目的、許容リスク、優先順位 |
| API契約 | Path、Method、Schema、Response、認証 | コード、クライアント、テスト案の生成 | 公開機能、互換性、認可方針 |
| ワークフロー | 呼出順序、依存、成功・失敗条件 | シナリオテスト、影響分析 | 業務上の正しい順序と例外 |
| 実装 | コード、IaC、Policy、テスト | 変更案、差分説明、検証実行 | 承認、例外、リリース判断 |
この表で最も重要なのは、AIの列だけではない。右端に人間が決めることを残している点である。AIは大量の候補を作ったり、決められた形式に変換したりするのは得意でも、「この会社では誰にどこまで顧客情報を見せるべきか」「誤って止めた場合にどれだけ業務へ影響するか」を単独では決められない。技術を導入する前に、機械へ渡せる判断と、人間が責任を持つ判断を分ける必要がある。
まず、Web画面とAPIの違いをつかむ
人がWebサイトを使うときは、画面に表示されたボタンや入力欄を見る。「カートへ入れる」というボタンを押せば、裏側で商品番号や数量がサーバーへ送られる。利用者は通信内容を意識しなくても操作できる。
一方、別のプログラムには画面の見た目が通じない。どのURLへ、どの方法で、どの項目を送るかを正確に決める必要がある。このプログラム向けの窓口がAPIである。ここでいうURLは窓口の住所、Methodは「読む」「登録する」「更新する」といった用件、Requestは依頼書、Responseは結果通知だと考えるとよい。
たとえば配送状況を確認するAPIなら、次のような約束が考えられる。
| 項目 | 日常の窓口に置き換えた意味 | APIでの例 |
|---|---|---|
| Path | 窓口の住所 | /deliveries/123 |
| Method | 窓口で頼む用件 | GET（情報を取得する） |
| Request | 窓口へ渡す情報 | 配送番号123 |
| Response | 窓口から受け取る回答 | 配送中、配達済み |
| 認証 | 依頼者が誰かの確認 | ログイン時に発行されたToken |
| 認可 | その情報を見てよいかの判断 | 自分の注文だけ閲覧可能 |
最後の二つは似ているが別物である。認証が社員証の確認なら、認可はその社員が金庫室へ入ってよいかの確認に相当する。本人確認に成功しても、他人の注文や管理者専用情報を見てよいとは限らない。この区別は、後の記事でも何度も登場する。
APIを作っただけでは、これらの約束が自動的に文書化されるわけではない。実装担当者の頭の中、古い設計書、ソースコード、Gatewayの設定に約束が分散すると、どれが正しいか分からなくなる。そこで、共通して読める契約を先に用意する考え方が必要になるのだ。
APIは通信方式ではなく境界の記述である
OpenAPI Specificationは、HTTP APIをプログラミング言語に依存せず記述し、人間とコンピュータの双方がソースコードや通信観測なしにサービスの能力を理解できるものとして定義している。OpenAPI Descriptionは、ドキュメント、サーバーやクライアントのコード、テストなどへ利用できる。つまりAPIの価値は、単にシステム同士をつなぐことではなく、境界を再利用可能な形式知にできる点にある。1
たとえば「会員情報を更新する」という要求だけでは、許される項目、最大長、未指定項目の扱い、権限、競合、監査ログが分からない。次のような契約があれば、少なくとも通信形状の曖昧さは減る。
paths:
/members/{memberId}:
patch:
operationId: updateMember
security:
- oauth2: [members.write]
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: false
properties:
displayName:
type: string
minLength: 1
maxLength: 80
required: [displayName]
この断片は、誰がどの会員を変更できるかまでは保証しない。しかし、許容Method、Content-Type、必須項目、型、長さ、未知プロパティの扱いを、実装とテストが共有できる。自然言語を捨てるのではなく、自然言語で決めたことを検証可能な契約へ降ろすのだ。
コードのような見た目に慣れていなくても、すべてを読める必要はない。この例から次の約束だけ読み取れればよい。
pathsは窓口の一覧で、/members/{memberId}は会員番号を指定する窓口を表す。patchは、会員情報の一部を更新する操作を表す。securityは、この操作にmembers.writeという権限が必要だと示す。application/jsonは、送信する本文がJSONというデータ形式であることを示す。displayNameは文字列で、1文字以上80文字以下でなければならない。additionalProperties: falseは、契約にない勝手な項目を受け付けないことを示す。
たとえば利用者がdisplayNameを空にして送れば、最小文字数の規則に違反する。81文字なら最大文字数に違反する。isAdministrator: trueという契約にない項目を追加して管理者になろうとしても、未知項目を拒否する設定に違反する。このように、文章だけだった約束を機械が検査できる形へ変えるのが機械可読化である。
機械可読とは、人が読めない形式にすることではない。人が決めた約束を、コンピュータも項目として認識できる形にすることだ。PDFの設計書に「表示名は80文字まで」と書いてあっても、通常はプログラムが自動でその一文を検査規則として使えない。OpenAPIのSchemaへ書けば、入力検査、テスト生成、説明書生成などへ同じ情報を再利用できる。
一つの契約を複数の作業で使う
API契約を作る価値は、きれいな説明書が一冊増えることではない。同じ定義を複数の工程で使える点にある。
業務担当者が確認する説明
|
v
OpenAPI契約
/ | \
v v v
入力検査 テスト 利用者向け文書
\ | /
v v v
実装との差分確認
開発者はサーバーや利用側のひな型を作れる。テスト担当者は、必須項目を欠かした場合や文字数を超えた場合の試験を作れる。セキュリティ担当者は、存在しないPathや許可されていないMethodを拒否する設定へつなげられる。AIも同じ契約を読み、変更候補やテスト案を作れる。人ごと、製品ごとに約束を書き直す回数が減るため、転記ミスも減らしやすいのだ。
ただし、OpenAPIファイルが存在するだけでは不十分である。実際のプログラムが別の入力も受け付けていたり、Gatewayの設定が古かったりすれば、文書と現実は食い違う。契約を価値あるものにするには、後で説明するテストと変更管理が欠かせない。
SchemaはAIの出力空間も狭める
AIの出力も、自由文よりSchemaで制約した方が後続処理へ接続しやすい。OpenAIのStructured Outputsは、開発者が与えたJSON Schemaへモデル出力を適合させる仕組みとして説明されている。これはOpenAPIそのものの効果を証明する資料ではないが、「AIと既存システムをつなぐとき、構造と制約が重要になる」という同じ方向を示している。2
ただしSchema適合は意味の正しさではない。memberIdが文字列であることを満たしても、その利用者に対象会員の更新権限があるとは限らない。AIが正しいJSONを出したことと、業務上正しい操作を選んだことも別問題である。
Schemaで確認できる
型 / 必須 / 長さ / 列挙 / 構造 / 一部の形式
Schemaだけでは確認できない
所有者認可 / 職務分離 / 残高整合性 / 操作順序 / 副作用 / 承認
ここでいう「型」は、値の大まかな種類である。名前は文字列、個数は整数、受付済みかどうかは真偽値、といった分類を指す。「必須」は空欄にできない項目、「列挙」は選べる値をあらかじめ限定した一覧である。Schemaは、書類の記入欄と記入規則を定めるものだと考えると分かりやすい。
しかし、書類の形式が正しいことと、申請内容が正当であることは別である。経費申請書に金額が数字で書かれ、日付も正しい形式で入っていても、その支出が業務上必要だったかはSchemaでは判断できない。申請者と承認者を同じ人にしてよいか、予算を超えていないか、領収書が本物かといった確認には別の規則がいる。
AIの出力も同じである。AIへ「注文データをJSONで作って」と頼み、指定どおりの商品番号、数量、住所が返ってきても、その商品を本当に注文してよいか、住所が本人のものか、在庫があるかまでは保証されない。構造を制限すると事故の種類を減らせるが、判断そのものをAIへ丸投げできるわけではないのだ。
AIに渡す前後を分けて考える
AIを使う処理は、入力、生成、検証、実行の四段階へ分けると理解しやすい。
- 入力：人間の依頼、既存のAPI契約、禁止事項をAIへ渡す。
- 生成：AIがOpenAPIの変更案、コード案、テスト案を作る。
- 検証：別のToolが文法、互換性、契約適合、安全性を確認する。
- 実行：人間の承認後に、決められた仕組みが変更を反映する。
AIが担当するのは主に二段階目である。三段階目は、同じAIの自己評価だけにせず、決められた結果を返す検査Toolを組み合わせる。四段階目は、重要度に応じて人間の承認を残す。こうすると、AIの提案速度を利用しながら、もっともらしい誤りが直接本番へ入る経路を狭められる。
単一APIから業務フローへ広げる
OpenAPIは一つのOperationを詳しく記述できるが、複数APIをどの順序で呼び、どの結果を次の入力へ渡し、何を成功とするかは別の論点である。Arazzo Specificationは、OpenAPIなどのAPI記述を使い、特定の結果を得るための呼出シーケンスと依存関係を表現する仕組みを定義している。2026年8月23日時点の最新公開版は1.1.0である。3
これにより、AIへ渡せる情報は「この関数を呼べる」から「申請を作成し、承認を受け、実行結果を確認する」へ近づく。ただし、Arazzoで書いた順序が業務上正しいかは、業務責任者が決めなければならない。形式化は正しさを発見する魔法ではなく、正しさをレビューできる場所を作るものなのだ。
単一の窓口が分かっても、業務全体が分かるとは限らない。旅行予約なら、「空席を確認する」「座席を一時確保する」「支払う」「予約を確定する」「確認通知を送る」という複数の操作がある。途中で支払いだけ成功し、予約確定に失敗した場合には、返金するのか再試行するのかも決めなければならない。
OpenAPIは、それぞれの窓口へ何を送るかを詳しく書くのに向いている。Arazzoは、それらをどの順序で利用して一つの目的を達成するかを書くための仕様である。地図にたとえるなら、OpenAPIが各施設の住所と利用条件、Arazzoが「受付の後に会計へ行き、最後に受取窓口へ進む」という道順に近い。
それでも「正しい道順」は業務によって変わる。高額な送金だけ上司承認を挟む、在庫切れなら代替商品を提案する、途中失敗なら確保を取り消す、といった判断は組織が決める。AIは既存資料から候補を整理できても、責任を伴う最終規則は人間が確認する必要がある。
API FirstをAI Firstと取り違えない
AIがあるからAPIを作るのではない。人間、プログラム、テスト、セキュリティ製品が共通して読める契約を作り、その利用者の一つとしてAIを加える。
契約を中心に置く開発では、変更の順序が変わる。
- 業務要求と禁止事項を定義する。
- OpenAPIと業務Policyの変更案を作る。
- 互換性、認可、データ、副作用をレビューする。
- 実装、テスト、Gateway設定の変更を生成する。
- Contract TestとSecurity Testで差分を検証する。
- 証跡を添えて人間がリリースを承認する。
AIは2、4、5を高速化できる。1と3と6まで無条件に自動化すると、曖昧な要求や誤った前提を高速で展開するだけになる。
API Firstは、まずAPIだけを作り、画面や業務を後回しにするという意味ではない。関係者が実装へ進む前に、外部へ見せる機能と約束を合意する進め方である。建物を造る前に、出入口、非常口、利用者の動線を図面で確認するのに近い。
AI Firstという言葉を「何でも最初にAIへ任せる」と受け取ると、順序が逆になる。曖昧な要求をそのままAIへ渡せば、AIは空白を推測で埋める。しかも出力が速いため、誤った前提からコード、テスト、設定が一気に増えることがある。速く作れたことと、正しいものを作れたことは同じではない。
会員情報へ項目を追加する例
既存の会員情報へ「緊急連絡先」を追加する変更で考える。
| 確認する順序 | 確認内容 | AIが支援できること |
|---|---|---|
| 目的 | 何のために集め、誰が使うのか | 要求文から未確定事項を列挙する |
| データ | 電話番号か、氏名も必要か、保存期間はどうするか | Schema案と説明文を作る |
| 権限 | 本人、家族、担当者の誰が閲覧・更新できるか | 既存Policyとの差分候補を示す |
| 互換性 | 古いアプリが新項目を知らなくても動くか | 破壊的変更の候補を検出する |
| 検証 | 空欄、誤形式、権限外閲覧を拒否できるか | テスト案を作り実行結果を整理する |
| 承認 | 個人情報として許容できる設計か | 証跡をまとめる。判断は責任者が行う |
この順序なら、AIは検討を速める補助役になる。目的や権限が決まる前にAIへ実装させると、後から多くの成果物を作り直すことになるのだ。
機械可読でも陳腐化すれば役に立たない
OpenAPIが実装とずれているなら、AIには古い地図を渡すことになる。契約を正本に近づけるには、少なくとも次の同期が必要である。
- Pull Requestで契約、実装、テストを同時にレビューする。
- 破壊的変更を検出し、互換性判断をリリース条件にする。
- 実トラフィックから未知Endpointを発見し、台帳との差を確認する。
- 契約適合だけでなく、認可、業務フロー、負荷、異常系を試験する。
- 生成物へ生成元の契約バージョンを記録する。
「正本」とは、複数の資料が食い違ったときに、最終的に正しいと扱う情報源である。紙の手順書、実装、Gateway設定、テストが別々に更新されると、どれが正しいかを人間が毎回調べることになる。OpenAPIを正本に近づけるとは、OpenAPIだけを信じることではなく、OpenAPIと現実が一致しているかを継続して確認することを意味する。
Pull Requestは、変更を本体へ取り込む前に差分を見せ、関係者がレビューする仕組みである。会員APIへ項目を追加するなら、OpenAPIだけでなく、実装、Gateway設定、テスト、利用者向け説明も同じ変更単位へまとめる。どれかが更新されていなければ、自動検査で止めるのが理想である。
「破壊的変更」は、既存の利用者が動かなくなる変更を指す。必須項目を突然増やす、これまで返していた項目を削除する、同じ項目の意味を変える、といった変更が該当する。AIは差分から候補を見つけられるが、影響を受ける利用者や移行期限は人間が判断する。
また、文書にないAPIが本番で動いていないかも確認する。古い試験用Endpointや、担当者だけが知る管理APIが残っていれば、OpenAPIが整っていても公開面を把握できていない。設計書と実通信を突き合わせる作業が必要なのだ。
API化すればAI駆動開発が成功するわけではない。成功条件は、契約が実装と同期し、契約で表せない判断を別のPolicyとテストへ分離できることなのだ。
一つの機能を要求から公開まで追ってみる
ここまでの要素を、「問い合わせ受付API」を作る例で一つにつなげる。Webサイトから氏名、連絡先、問い合わせ分類、本文を受け取り、担当部署へ渡す機能である。技術的には単純に見えるが、曖昧なままAIへ作らせると多くの判断が抜ける。
最初の要求が「問い合わせフォームをAPI化して、AIで早く実装する」だけだったとする。この文章からは、氏名が必須か、連絡先はMailだけか、本文の最大長、添付Fileの有無、誰が問い合わせを読めるか、Spam対策、保存期間が分からない。AIは一般的な例から推測して作れるが、それがこの組織の正解とは限らない。
1. 人間が目的と禁止事項を決める
まず、業務担当者、Data Owner、Security担当者が、少なくとも次を決める。
- 目的は、製品利用者からの質問を担当部署へ渡すこと。
- 氏名は任意、返信先Mail Addressは必須。
- 問い合わせ分類は、契約、障害、利用方法、その他の四種類。
- 本文は1文字以上4000文字以下。
- Credit Card番号やPasswordを入力しないよう案内する。
- 添付Fileは初期版では受け付けない。
- 問い合わせ内容は担当部署だけが閲覧できる。
- 保存期間と削除方法はData管理規則に従う。
この段階は自然言語でよい。重要なのは、AIが推測してはならない組織の判断を先に出すことだ。決まっていない項目は、未確定として残す。
2. AIがAPI契約の案を作る
AIは、決められた要求をOpenAPIのSchemaへ変換する。emailは必須の文字列、categoryは四種類から選択、messageは最大4000文字、未知の項目は拒否、といった案を作れる。正常時と失敗時のResponse例も作れる。
このときAIが、要求にない電話番号や住所を追加したら、人間は削除する。一般的な問い合わせFormでは便利でも、この組織では収集目的がない個人情報かもしれない。AIの提案は候補であり、収集してよいDataの承認ではない。
3. 契約から実装とTestを作る
承認されたOpenAPIから、Server側の入力型、利用側のClient、Contract Testを作る。AIは実装Codeの下書きと、次のようなTest案を作れる。
| Test | 入力 | 期待する結果 |
|---|---|---|
| 正常 | 正しいMail、分類、本文 | 受付番号を返す |
| 必須不足 | Mailなし | 受付前に拒否 |
| 未知分類 | sales-call | 許可した四種類ではないため拒否 |
| 長すぎる本文 | 4001文字 | 上限超過として拒否 |
| 未知項目 | isAdmin: true | 契約外項目として拒否 |
| 権限外閲覧 | 別部署の担当者が内容を読む | 認可で拒否 |
最初の五つは主にSchemaとContract Testで扱える。最後の権限外閲覧は、Schemaではなく認可PolicyとSecurity Testで扱う。この分離が重要である。
4. 別の検査でAIの案を確かめる
OpenAPIの文法はLint Toolで検査する。実装と契約の一致はContract Testで確認する。外部Libraryの脆弱性はSCA、Code上の問題はSASTなど別の検査を使う。AIが自分で「正しい」と評価した文章だけを証拠にしない。
業務担当者は、分類と受付結果が実際の運用に合うかを見る。Security担当者は、入力Size、Rate Limit、認可、Logへの個人情報記録を確認する。Data Ownerは、収集目的と保存期間を確認する。同じAPIでも、見るべき正しさが違う。
5. 公開後の現実と比べる
公開後、契約にない古いClientが通信していないか、Errorが増えていないか、Spamで受付処理が圧迫されていないかを見る。Schemaに合う問い合わせでも、大量送信は業務濫用になりうる。実際の利用から新しい問題が分かれば、要求とPolicyへ戻して変更する。
この通し例で、AIとAPIの相性が「Code生成が速い」という一点ではないことが分かる。要求を契約へし、契約から複数の成果物を作り、別のToolとOwnerが検証し、本番との差を次の変更へ戻す。AIはこのLoopのいくつかを速めるのだ。
よくある誤解を言い換える
| よくある言い方 | より正確な読み替え |
|---|---|
| APIならAIが理解できる | 機械可読で実装と同期したAPI契約なら、AIが構造を扱いやすい |
| Schemaがあれば安全 | 入力の形は狭められるが、認可と業務上の正しさは別に必要 |
| AIがTestも作るから正しい | 同じ誤解から実装とTestを作る可能性があるため、別の根拠で検査する |
| OpenAPIを正本にすれば終わり | 実装、Gateway、実通信との差を継続して確認する必要がある |
| AI Firstで先に作る | 目的、禁止事項、責任を人が決め、AIは構造化と差分作成を支援する |
専門用語を覚えるより、この読み替えを持っておく方が設計の過大評価を避けやすい。
非技術者が会議で確認する五つの質問
OpenAPIの記法を読めなくても、設計の良し悪しを確認することはできる。企画、業務、監査、管理の立場なら、次の五つを尋ねればよい。
- このAPIで外部へ公開する機能は何か。公開しない機能は何か。
- 入力の形式だけでなく、誰がどの情報を扱えるかをどこで決めているか。
- 契約、実装、Gateway、テストの変更は同じ単位で確認されるか。
- AIが作った案を、AI以外の検査と責任者が確認するか。
- 古い利用者や想定外の通信を止める前に、影響を観測できるか。
この五つに答えられなければ、AIやAPIという新しい言葉があっても、境界と責任が曖昧な可能性が高い。反対に、答えが明確なら、技術の細部を知らなくても設計の意図を追いやすくなる。
この回で覚えておくこと
- APIは、別のシステムから機能を利用するための窓口である。
- OpenAPIは、その窓口の住所、用件、入力、出力などを機械可読にする。
- Schemaはデータの形を検査できるが、権限や業務上の正しさまでは保証しない。
- AIは契約から変更案やテスト案を作れるが、目的、許容リスク、承認は人間に残す。
- 契約は作って終わりではなく、実装、設定、実通信と同期させる必要がある。
つまり、AIとAPIの相性とは「AIならAPIをうまく呼べる」というだけの話ではない。曖昧だった約束を、人間と機械が同じ形で確認し、間違いをテストできるようにすることが本質なのだ。
次回へ
機械可読な契約は、開発だけでなく実行時防御にも使える。次回は、既知の悪い通信を探すWAFに、許された通信形状を定義するPositive Securityをどう重ねるかを扱う。
用語集
| 用語 | 平易な説明 |
|---|---|
| API（Application Programming Interface） | システム同士が、決められた形式で情報や機能をやり取りするための窓口。 |
| HTTP | Webで情報を送受信するための通信ルール。APIでも広く使われる。 |
| OpenAPI | APIの窓口、入力、出力、認証方法などを、人間とコンピュータの双方が読める形で記述する標準仕様。 |
| 機械可読 | 文章を人が読むだけでなく、コンピュータが項目や制約を自動処理できる状態。 |
| API契約 | APIが「何を受け取り、何を返し、何を拒むか」という利用者と提供者の約束。 |
| Schema（スキーマ） | データに必要な項目、型、長さなどを定めた設計図。JSON SchemaはJSONデータ向けの記述方式。 |
| Path／Endpoint | APIの個々の窓口を示すURL上の場所。たとえば/orders/123は特定の注文を扱う窓口になる。 |
| HTTP Method | 取得、登録、更新、削除など、窓口で行いたい操作を示す種類。代表例はGET、POST、PUT、DELETE。 |
| Request／Response | Requestは利用者からAPIへの要求、ResponseはAPIから返る結果。 |
| Content-Type | 送るデータの形式を示す情報。たとえばapplication/jsonはJSON形式を意味する。 |
| 認証／認可 | 認証は「誰か」を確かめること。認可は、その人が「その操作をしてよいか」を判断すること。 |
| Structured Outputs | AIの出力を指定したSchemaに合わせる仕組み。自由文より後続処理へ渡しやすい。 |
| Arazzo | 複数のAPIをどの順番で呼び、前の結果を次へどう渡すかを記述するOpenAPI Initiativeの仕様。 |
| API First | 実装を始める前にAPI契約を設計し、関係者の共通基準として使う進め方。 |
| Policy（ポリシー） | 誰が何を許されるかなど、Schemaだけでは表しにくい判断ルール。 |
| Contract Test | 実装がAPI契約どおりに入出力するかを自動確認するテスト。 |
| Pull Request | 変更内容を本体へ取り込む前に、差分、テスト結果、承認をまとめて確認する仕組み。 |
| 破壊的変更 | 既存の利用者がそのままでは動かなくなる変更。項目の削除や意味の変更などが該当する。 |