#07 APIって何？から始めた私が、初めて「本物の外部API」に接続した日｜HTTP 200でもDBに書き込まなかった理由
「APIを使えばできます」
AIにシステム開発を相談していると、この言葉がよく出てきます。
でも、プログラミング未経験の私にとって、最初の頃の「API」はかなり曖昧な言葉でした。
何か便利な仕組みらしい。
サービス同士をつなぐものらしい。
URLにアクセスするようなものらしい。
その程度です。
前回の#06では、私が開発中の「note-affiliate-manager」で、明示的に許可するまで従量課金の有料APIを使わず、AI運用コストを¥0に固定している理由を書きました。
では、APIそのものを一切使っていないのか。
そうではありません。
実際の開発では、楽天側の外部APIへ実接続する検証を行いました。
結果は2回とも、
HTTP 200
商品データ1件取得
1 HTTP request
DB書き込み0
DBハッシュ不変
でした。
「成功したなら、そのままDBへ登録すればいいのでは？」
以前の私なら、そう考えたかもしれません。
でも今回は、取得できたことと、保存してよいことを分けました。
この記事では、APIという言葉自体がよく分からなかった非エンジニアが、ChatGPTとClaude Codeを使いながら、初めて外部APIの「本番データ」に触れたとき、なぜHTTP 200でも自動登録まで進めなかったのかを、できるだけ専門用語を使わずに説明します。
そもそもAPIって何？
難しい定義はいったん置いておきます。
私が理解するために使っているイメージは、
「別のサービスに、決められた形式で質問して、決められた形式で答えを受け取る窓口」
です。
たとえば自分のシステムから、
「この商品コードの商品情報をください」
と楽天側のAPIへ問い合わせる。
すると、条件が正しければ商品名やURLなどのデータが返ってくる。
人間がブラウザで商品ページを開いて読む代わりに、システム同士がデータをやり取りするための窓口、と考えると私は理解しやすくなりました。
もちろん実際には認証、パラメータ、レスポンス、エラー処理などがあります。
でも、非エンジニアが最初から全部覚える必要はありませんでした。
まず重要だったのは、
「外部のサービスへ問い合わせる処理である」
と理解することでした。
HTTP 200は「全部成功」の意味ではなかった
実接続をすると「HTTP 200」という結果が返りました。
最初に見ると、かなり技術者っぽい数字です。
簡単に言えば、今回の文脈では、
「問い合わせ自体は正常に処理され、応答を受け取れた」
と考えれば十分です。
実際、商品データも1件取得できました。
ここだけ見れば成功です。
ただし、
APIへの問い合わせが成功した
と
取得したデータを自分のDBへ保存してよい
は別の判断です。
ここが今回、一番大きな学びでした。
「取れた」と「登録していい」を分ける
note-affiliate-managerでは、将来的にアフィリエイト案件を管理する機能も作ろうとしています。
外部APIから候補商品を取得できれば、システムへ登録したくなります。
でも、実データを書き込むと、それは単なるテストではなくなります。
DBの状態が変わります。
間違った商品を登録するかもしれません。
必要なURLが欠けているかもしれません。
重複するかもしれません。
後から「どのテストで入ったデータか分からない」という状態になるかもしれません。
だから今回は、
外部APIへ問い合わせる
↓
データを1件取得する
↓
内容を検証する
↓
DBには書き込まない
↓
人間が確認する
という段階に分けました。
これまでの記事で何度も出てきたHuman Gateを、API接続にも置いた形です。
実際の検証結果
今回、楽天APIへの実接続は2回行いました。
2回とも確認できた範囲は同じでした。
・HTTP 200
・商品データ1件取得
・HTTP requestは1回
・DB書き込み0
・DBハッシュ不変
「DBハッシュ不変」という言葉も、最初は意味が分かりませんでした。
私の理解では、
「テストの前後でDBの中身が勝手に変わっていないことを確認する指紋」
のようなものです。
ファイルの内容が変われば、通常はハッシュ値も変わります。
前後で同じなら、今回の検証によってDBを書き換えていないことを確認する材料になります。
つまり今回は、
外からデータを受け取るところまでは試した。でも、自分のデータベースへ登録するところには進んでいない。
という状態です。
なぜ2回も試したのか
1回成功したら十分に見えます。
ただ、1回だけでは偶然うまくいった可能性もあります。
同じ安全条件で再度実行し、
HTTP 200。
1件取得。
1 request。
DB書き込み0。
DBハッシュ不変。
という結果をもう一度確認しました。
ここでも大切なのは、「2回成功したから完成」とはしていないことです。
確認できたのは、あくまで今回の実接続検証の範囲です。
さらに見つかった「登録してはいけない条件」
実装を進める中で、取得したデータに必要なアフィリエイトURLが存在しないケースをどう扱うか、という問題も出ました。
そこで、
affiliateUrlが欠けていたら登録を拒否する
というfail-closed条件を追加しました。
fail-closedは、このシリーズで何度も使っている考え方です。
難しく言えば安全側に倒す設計ですが、私の理解では、
「判断材料が足りなければ、勝手に進まず止まる」
です。
商品データが取れた。
商品名もある。
でも、アフィリエイトURLがない。
そんなときに「たぶん大丈夫」と登録しない。
必要条件を満たさなければ止める。
これなら非エンジニアの私でも、何を安全条件にしているのか理解できます。
テストは994件すべてPASSした。でもHuman Gateは残した
この変更後、フルテストでは994テストすべてPASSしました。
さらに、
・不要なarticle_affiliate_linksを生成しない
・重複登録を拒否する
・affiliate URLがない場合は拒否する
といった確認も行われました。
ここまで聞くと、また「では登録まで自動化していいのでは？」と思います。
でも、#05で書いた通り、
自動テスト成功と、本番データを書き込んでよいかは別です。
実際の候補をDBへ本番登録する手前にはHuman Gateを残しました。
つまり、
API接続成功
≠
自動登録許可
です。
非エンジニアにとって怖いのは「分からないまま進むこと」
APIという言葉を知らないこと自体は、大きな問題ではありませんでした。
分からなければChatGPTに説明してもらえます。
Claude Codeに実装内容を調査してもらえます。
本当に怖いのは、
「HTTP 200だから成功らしい」
「テストも全部PASSしたらしい」
「AIが問題ないと言っている」
という情報だけで、自分が何を許可したのか分からないまま次へ進むことでした。
だから私は、技術用語を全部覚える代わりに、
どこから外部へ通信するのか
どこで自分のデータが変わるのか
どこからお金が発生する可能性があるのか
どこで人間が止められるのか
を見るようにしています。
この4つなら、コードが読めなくても確認できます。
#06の「有料APIを使わない」と矛盾しないの？
ここは誤解が出やすいので明確にします。
#06で書いた「0円」は、
明示的に許可するまで、システム運用で従量課金の有料API利用料を発生させない
という方針です。
今回の記事は「APIという仕組み自体を禁止している」という話ではありません。
APIにはさまざまな料金体系や利用条件があります。
大事なのは、
APIかどうかではなく、利用条件・料金・安全条件を理解してから使うこと。
です。
「有料APIを勝手に導入しない」と「外部APIを安全に検証する」は両立します。
API接続で私が覚えた5つの言葉
ここまで読んで、「専門用語が多い」と感じる方もいると思います。
私もそうでした。
今回の範囲なら、まず次の5つだけ理解すれば十分でした。
1. API
別サービスへ決められた形式で問い合わせる窓口。
2. Request（リクエスト）
こちらからAPIへ送る「質問」。
3. Response（レスポンス）
APIから返ってくる「回答」。
4. HTTP 200
今回の文脈では、問い合わせが正常に処理され、応答を受け取れたことを示す状態。
5. DB
自分のシステムが管理するデータの保管場所。
この5つが分かるだけでも、
「外部へ質問した」
「答えが返った」
「でも自分のDBにはまだ保存していない」
という今回の流れを追えるようになりました。
今回、私が一番伝えたいのは、
API接続成功と、本番登録成功を一つの「成功」にまとめない
ということです。
外部APIからデータを取得する。
内容を検証する。
DBへ書き込む。
本番運用する。
これらは別々の段階です。
非エンジニアだからこそ、一気に自動化するのではなく、境界ごとにHuman Gateを置く。
ここから有料部分では、私が外部APIを初めて扱うときに使える形へ整理した、
・外部API接続を5段階に分ける方法
・Claude Codeへ渡す「まずread-only」プロンプト
・DBを書き換えない確認方法
・APIレスポンスの最低限チェック
・本番登録前Human Gate
・失敗時に勝手に進ませないfail-closed条件
・購入特典「初めての外部API安全確認シート」
をまとめます。
