AIでAPI呼び出しコードのたたき台を作る方法

AIにAPIコードを書かせるなら、完成したアプリを一度に作らせず、公式仕様を渡して「1回だけ成功する最小Request」を作ります。最初に固定するのは実行環境、認証、入力、期待する出力、失敗時の扱いです。コードが実行できた後にだけ、保存・画面・自動再試行などを追加します。

コード生成の前に、使うAPIの公式QuickstartとReferenceを開き、method、endpoint、認証方式、必須パラメータ、Response、Error形式を確認してください。AIにAPI仕様を推測させないため、参照URLと対象のAPI版を渡し、分からない箇所は不明と書くよう指定します。

まずInput Contractを作る

表は横にスクロールできます

項目	決める内容	未確定のまま進めた場合
Provider / API	利用するサービスと公式Reference	別APIの仕様が混ざる
Runtime / version	Node.jsやPython、実行環境	SDKや構文が合わない
実行場所	ServerかBrowserか	Secretを公開コードへ置く危険
入力	固定文字列など最小の1件	過不足のあるRequestになる
出力	必要なResponse field	不要な情報を保存・表示する
失敗時	認証、入力、制限、一時障害の扱い	Retryやエラー表示を誤る
副作用	保存、送信、課金、外部更新の有無	二重実行の影響を見落とす

APIの種類によってRequest/Responseの形は異なります。この表にある「text」「id」などは作業の枠であって、特定APIにそのfieldが存在するという意味ではありません。必須fieldが公式資料に見つからない場合はコードで補わず、その箇所を確認事項として残します。

最小Requestの完成条件

最初の版は、テスト用入力を一件送り、成功・失敗のどちらでも状況が分かるところまでにします。

固定Input

  ↓

入力の形式を確認

  ↓

Server側からAPIへ1回Request

  ↓

HTTP結果とResponse形式を確認

  ↓

必要なfieldだけ安全に表示

最初のRequestでは、実顧客データや本番データを使わず、テスト用の無害な値を使います。DB書き込み、メール送信、決済、チケット作成などの副作用は追加せず、APIから返る最小の値を確認します。実行するたび課金や状態変更が起きるAPIなら、テスト用環境と利用条件を先に確認します。

AIへ渡す依頼例

この公式API資料を前提に、1回だけ呼び出す最小コードを作ってください。

公式資料：https://provider.example/docs/endpoint（使用前に実URLへ置換）

API版：公式資料に記載された版。分からなければ質問する。

Runtime / version：Python 3.x

実行場所：Server

認証：環境変数または承認済みSecret管理から読む

Input：機密を含まない固定テスト値1件

Output：必要なresponse fieldだけ表示

制約：

- endpoint、method、field名、auth方式を推測しない

- API keyや実データをコード・出力へ書かない

- 保存や外部更新などの副作用を追加しない

- まず1回実行し、status・error・responseを切り分ける

- 資料にない仕様は「要確認」とする

依頼に含める公式URLは、例のplaceholderではなく実際のProvider資料に差し替えます。URLが開けること、対象バージョンの資料であることを確かめ、AIがその内容を読めない環境なら、必要な仕様を確認してから短い抜粋を渡します。

Code Skeleton：仕様を確定してから埋める

次は構造を示すための疑似コードです。<...>部分、認証ヘッダー、Request bodyはAPIごとに異なるため、そのまま実行できるコードではありません。

token = read_secret_from_server_environment()

payload = validate_and_build_request(test_input)

try:

    response = send_one_request(

        endpoint=OFFICIAL_ENDPOINT,

        method=OFFICIAL_METHOD,

        headers=OFFICIAL_AUTH_HEADERS(token),

        body=payload,

        timeout=EXPLICIT_TIMEOUT,

    )

    result = parse_response_using_official_schema(response)

    show_only_required_fields(result)

except AuthenticationError:

    report_configuration_problem_without_secret()

except InvalidRequestError as error:

    report_safe_error_details(error)

except RateLimitOrTemporaryError as error:

    record_retry_guidance_without_replaying_side_effects(error)

公式SDKが提供されている場合は、独自のHTTP組み立てよりSDKの公式Quickstartを使う方がよい場合があります。SDKの名前、初期化方法、Responseの取り出し方も資料で確認します。AIが書いたimport文やMethod名を、パッケージの存在確認前に採用しないでください。

RequestとResponseを照合する

実装前に、公式資料からRequest Contractを手で埋めます。必須fieldと任意fieldを分け、型、許容値、文字コード、サイズ制限、認証ヘッダーを記録します。続けてResponse Contractに、成功時の必要field、エラー時に返る値、個人情報やSecretをログへ出さない条件を書きます。

表は横にスクロールできます

確認欄	例として記録する内容
Method / endpoint	公式Referenceに記載の値
Authentication	正式な場所・方式。秘密の実値は書かない
Required input	名称、型、範囲、上限
Success response	必要なfieldと型
Error response	status、error code/messageの所在
Trace identifier	公式Responseにある場合だけ扱う

RequestとResponseを照合したら、テスト値一件について送信内容をログまたはデバッガで確認します。Authorization header、API key、Cookie、個人情報はログへ出しません。入力が不正ならRequestを送らず、どのvalidationで止めたかだけを安全に記録します。

Secretと実行場所

API keyは、公開リポジトリ、HTML、ブラウザへ配るJavaScript、画面キャプチャ、エラーログへ直接書きません。OpenAIの公式API資料は、API keyを秘密として扱い、ブラウザ等のクライアント側へ露出させずServer側で読み込む方法を説明しています。別Providerも同じだと決めつけず、そのProviderの認証資料を確認してください。

環境変数の名前はデプロイ環境の契約に合わせます。.envをGitへ追加しないこと、誤って出力した秘密をログ履歴から消しても漏えいが解決したことにはならないこと、漏えい時にはProviderの手順でkeyを失効・再発行することを確認します。コード生成時は常に<API_KEY>などのplaceholderを使い、実値をAIへ貼り付けません。

Errorの切り分け

HTTP statusだけで、すべてのProviderの意味や再試行可否を決めつけないでください。OpenAI APIのError資料では、認証、無効なRequest、Rate Limit、サーバー側の問題などを区別して説明しています。他のAPIではResponse body、独自error code、Retry-Afterの扱いが異なる場合があるため、利用中のAPIの公式資料に従います。

表は横にスクロールできます

観察結果	最初に見る場所	対応の考え方
認証拒否	実行環境のSecret名、権限、失効	keyを表示せず設定と権限を確認
入力拒否	必須field、型、範囲、API版	Requestを直してから再度テスト
利用制限	上限、時間窓、Retry指示	契約・公式の再試行条件を確認
一時障害	status、公式error code、request idがあれば記録	副作用がないことを確認してから再試行を判断
Timeout	相手側で処理が完了した可能性	状態照会や冪等性を確認するまで再送しない

特にタイムアウトは、サーバーが処理を行った後で応答だけが失われた可能性があります。外部への登録・送信などを伴う処理では、同じRequestを無条件に再送すると重複する場合があります。APIが提供する冪等キーや状態照会を使えるか公式資料で確かめ、仕様が不明なら自動Retryを加えず人が確認できる状態にします。

OpenAIのError資料にあるstatusやヘッダーの扱いはOpenAI APIに関する説明です。別Providerや自社APIへそのまま一般化せず、現在使う仕様に置き換えます。再試行は「一時的だから」と一律に行わず、error種別、処理の副作用、再送条件、待機時間の根拠を明示します。

小さく動かす検証手順

1. Provider、公式Endpoint、API版、Runtimeを記録する。

2. SecretがServer環境だけにあり、コードやログへ出ないことを確認する。

3. 無害な固定値を用い、入力Validationを通す。

4. APIへ一回Requestし、statusとResponse schemaを確認する。

5. 成功時に必要なfieldだけ抽出し、期待値と照合する。

6. 認証失敗または不正入力をテスト環境で一件試し、秘密を出さず失敗を識別できるか確認する。

7. 副作用、Retry、保存がない状態を確認してから次の機能へ進む。

検証用のメモは、ケース、入力（秘密を除く）、期待する結果、実際のstatus、必要field、次の処置で構成できます。接続失敗がDNS・TLS・認証・アプリ層のどこかを切り分けるには、最初の失敗をまとめて「APIが動かない」と扱わず、段階ごとの結果を記録します。

最小実装からApplicationへ広げる

最小Requestが確認できたあとに、型定義、ユーザー入力Validation、timeout、必要なRetry、保存、画面表示の順で追加します。各段階で一つの責務だけを変え、前の成功ケースが再現するか確かめます。DB書き込みを足すときは、失敗時の再実行が二重登録にならないか、保存前後の状態を明示します。

ログには処理の開始・終了、失敗分類、Providerのrequest ID（公式Responseにあり安全に記録できる場合）など、調査に必要な最小情報を残します。Request bodyやAuthorization headerを丸ごと保存すると、入力データや秘密が蓄積します。ログのアクセス権、保管期間、マスキング方法も実装前に確認します。

コードレビューでは、AIが書いた行だけを眺めず、入力からAPI送信、出力、失敗、再試行までを順に追います。未使用の認証情報、不要な権限、例外を握りつぶす処理、成功したように見せるfallbackがないか確認します。仕様を確かめられない箇所はTODOではなく「リリース前に確認が必要」と明記し、実装の完了扱いにしません。

AIものさしの判断

APIコード生成は、Official Spec→Runtime→Auth→Input Contract→Minimal Call→Error Handling→Integrationの順に進めます。AIは雛形を作れますが、endpoint・認証・field・エラー意味を決めるSource of Truthではありません。まず固定入力で1回の動作を確かめ、仕様・秘密・副作用の境界が確認できてからApplicationへ広げます。