AIでAPIクライアントを作る｜契約・認証・エラーの整合を確認

契約の版と提供元を固定する

OpenAPIはHTTP APIを記述する仕様であり、AIが想像したパスや項目を正しくする仕組みではありません。利用するAPIの公式スキーマ、版、サーバー、認証方式を先に固定します。スキーマと実際の応答が違うなら、その差を未確定のまま示し、勝手にクライアント側で吸収しないでください。架空の例では注文一覧APIを題材に、提供元の契約にある項目だけを対象にします。開発用と本番のURLを明確に分け、契約ファイルの版をコードと一緒に残すことで、後から生成し直す根拠を追えます。

型だけでは欠落と空値を区別できない

注文の備考が未指定、null、空文字のどれを取り得るかを契約で確認します。番号が数字のように見えても識別子が文字列なら、数値へ変換して先頭ゼロを失わないようにします。金額や日時も、勝手な丸めや端末のタイムゾーンを加えないでください。AIには型の生成だけでなく、契約上の意味と変換を行う場所を説明してもらいます。見本は正常値だけでなく、任意項目がない応答、未知の追加項目、想定外の値を含め、どこで拒否しどこを保持するかを人が判断します。

• AIでユニットテストを作る｜正解の根拠と境界値を確認する

認証と再試行を別の設計にする

認証情報の取得先、期限切れ、権限不足を整理し、秘密値をコードや会話へ埋め込みません。期限切れの認証を更新する処理と、通信失敗後の再試行は別の条件です。特に注文作成などの更新系は、同じ要求を送り直すと二重処理になる場合があります。公式契約にある冪等性や再試行の条件を確認し、情報がなければ無条件の自動再送を追加しないでください。読み取りだけの試用から始め、更新を行う試験は見本環境で意図したデータだけに限定すると、失敗時の影響を追いやすくなります。

架空の例：二ページ目の注文一覧

架空の注文一覧では、最初のページだけでなく次ページ、最後のページ、空の結果を確認します。カーソルや件数の意味は対象APIの契約に合わせ、ページ番号と混同しません。途中でエラーになった時に既存の結果を残すか、やり直すかも決めます。AIへは契約の例と期待する画面状態を渡し、同じ注文を二重に表示しないことを確認してください。この演習は特定APIの挙動を報告するものではありません。一回の成功からは分からない一覧取得の境界を、コードと利用者の見え方の両方で確認する課題です。

• 依存更新後の不具合をAIで調べる｜再現条件と変更範囲

生成コードと契約テストを分ける

CursorやClaude Codeで周辺実装を調べ、Aider等で対象ファイルを絞る場合も、検証の期待値は契約から独立して作ります。モックが成功したことと、実際の認証や通信が成立したことは別に記録します。型検査に通すため不明な応答をすべて曖昧な型へ変えていないかをレビューしてください。再生成する部分と、人が保守するアダプターを分ける設計も候補です。試用では同じ契約変更を一件ずつ反映し、不要な画面や保存処理へ修正が広がらないことを採用条件にします。

契約変更と引き継ぎの費用

有料化を検討する前に、契約調査、生成、確認、手直しに使った時間と利用量を記録します。文脈を増やすだけで解決しない場合は、欠けた公式スキーマや見本応答を先に探します。引き継ぎには契約の版、再生成方法、必要な設定名、エラー方針、未確認の操作を含めてください。モデル契約を止めても通常のコードとして保守できることが目安です。API提供者の利用契約と開発ツールの契約は別なので、片方をやめる時にもう片方の稼働や請求まで変わるとは判断しません。

• モノレポをAIで修正する｜共有パッケージの影響範囲を確認