APIドキュメントに基づく呼び出しコードの作成

仕様書を貼り付けて認証まで対応した実用コードを生成する

なぜこう書くのか

役割

あなたは外部API連携の実装経験が豊富なエンジニアです。以下に貼り付けたドキュメントに記載されている内容のみを事実として扱い、ドキュメントにないURL・パラメータ・デフォルト値などを勝手に捏造しないでください。

文脈

私は{{使用言語}}で実装を行っており、やりたい処理は次の通りです: {{依頼内容}}

課題

ドキュメントを読み込み、このリクエストを処理する呼び出しコードを作成してください。認証ヘッダーの付与やレスポンスの確認処理まで含めてください。

聞き返し

コードを書く前に、ドキュメントの情報だけでは確定できない点があれば先に質問をしてください。質問は最大3点までとし、私が回答するまでコードは書かないでください。

形式

回答は3つのセクションに分けてください。まず「このコードが送信するリクエスト」の要約（メソッド・URL・必須ヘッダー・本文の項目）を表形式で示し、次にそのまま実行可能なコードブロックを1つ、最後に「ドキュメントから確認できず仮定したこと」の一覧を記載してください。

制約

APIキーはコードに直接ハードコードせず、環境変数から読み込むようにしてください。ドキュメントに記載されたエラーレスポンスはすべてハンドリングしてください。ドキュメントにないリトライルールや外部ライブラリを勝手に追加せず、必要だと判断した場合はコードではなく仮定一覧に記載してください。

入力資料

APIドキュメント: """ {{APIドキュメント}} """

API連携コードを仕様書なしで依頼すると、AIは過去の記憶を頼りにコードを書きます。その結果、一見正しそうに見えてもURLやパラメータ名が微妙に間違っているコードになりがちです。数年前のエンドポイント、すでに廃止されたオプション、存在しないレスポンスフィールドなどが混ざり込みますが、見た目はまともなため実行するまでミスに気づけません。仕様書を貼り付けるだけで、この問題の半分は防げます。

残りの半分を解決するのが質問による確認です。ドキュメントには通常リクエスト形式しか書かれておらず、呼び出し頻度や失敗時の挙動、使用するタイムゾーンなどは記載されていません。質問なしでコードを書かせると、AIは勝手な解釈で隙間を埋めてしまい、後からバグの原因になります。「私が回答するまでコードは書かないでください」と明記するのは、この指示がないと質問を3つ投げつつその下ですぐにコードを書いてしまうためです。

ドキュメントを """ で囲むのは明確な区分けのためです。貼り付ける仕様書には「この値を使用してください」といった説明文が多く含まれており、区切らないとAIがそれをプロンプト自体の指示と誤認して予期せぬ挙動を起こします。外部ドキュメントを読み込ませる際は特に必須のテクニックです。

制約の中で実務上最も役立つのは最後の一文です。AIは仕様の隙間を見るとリトライ処理や便利なライブラリを勝手に追加しがちですが、これをコード内ではなく「仮定一覧」として外に出させることで、どこまでが仕様書に基づくものでどこからが推測なのかを一目で判別できます。また、キーを環境変数から読み込ませる制約は、サンプルコードを誤ってそのままコミットしてキーがリポジトリに残る事故を防ぎます。

用語が分からなければAha AIで: hallucination, prompt-injection

悪い例との比較

よくある悪い例

SMS送信APIをPythonで呼び出すコードを書いて

すぐにコードが出力されますが、どのサービスのどのバージョンなのか分かりません。ヘッダー名が実際の仕様と異なっていたり、本文の必須項目が抜けて401や400エラーが返ってきます。何が間違っているのかを調べるために結局ドキュメントを開くことになりますが、その時点ではコードを半分信じてしまっているため、間違いを見つけるのが余計に難しくなります。

バリエーション

エラーの原因を特定したいとき

以下のAPIドキュメント通りにリクエストを送りましたがエラーが発生します。コードを新しく書き直すのではなく、ドキュメントと私のリクエストを突き合わせて不一致な点だけを指摘してください。「ドキュメントの要件・現在送信している内容・差異」を表形式で整理し、ドキュメントだけでは判断できない項目は「要確認」として残してください。

""" {{APIドキュメント}} """

連携のトラブルは新規コードではなく突合によって解決することがほとんどです。新しく書かないよう指示することで、原因究明を飛ばして別のコードを提示されるのを防ぎます。

英語のドキュメントを先に把握したいとき

以下のAPIドキュメントを読み、{{依頼内容}}に必要な部分だけを日本語で整理してください。コードはまだ書かないでください。「エンドポイント・認証方式・必須パラメータ・任意パラメータ・エラーレスポンス・呼び出し制限」の順で箇条書きにし、ドキュメントに記載がない項目は「記載なし」と明記してください。

""" {{APIドキュメント}} """

ドキュメントが長い場合はコード生成の前に使います。「記載なし」と書かせることで、推測で埋められた要約と区別できます。

モデル別の注意

ドキュメントのリンクだけを渡すとモデルがページを開けず、記憶にある古いバージョンで回答する可能性があります。ドキュメント本文を直接貼り付ける方が確実です。

ドキュメントが非常に長い場合は、認証・エンドポイント・エラーレスポンスの部分だけを抜粋して貼り付ける方が精度が上がります。知名度の高いサービスほどモデルが記憶で仕様の隙間を埋めようとするため、その場合は「貼り付けたドキュメントにない内容はコードではなく仮定一覧に記載してください」と念押ししてください。