APIとは？非開発者の店主のための入門ガイド

こんにちは、3Min APIの開発をリードしているyeonghyeonです。

前回のデータベース編では、ワインショップ店主の物語を締めくくりつつ、一つだけ後回しにしていた話があります。「オンラインショップが開けば、店舗POS・ウェブサイト・提携レストランからの注文が自動で同じデータベースに積み重なる」と言いましたが、その「自動で」という言葉の裏にある道具こそが今日のテーマです。それがAPIです。

今日の記事の目的は一つです。APIという言葉の裏にある複雑な技術を勉強する前に、まず「自分のビジネスの流れを頭の中ではなく、約束されたメッセージとして整理する感覚」をつかむこと。この感覚さえ身につけば、残りは必要なときに自然とついてきます。前提知識はなくても大丈夫です。

APIとは何か

辞書的な定義から短く見ていきます。ウィキペディアはAPI（Application Programming Interface）を「アプリケーションが互いに機能やデータをやり取りできるようにするための取り決め」と説明しています。

一行で要約するとこうです。

API = システム同士が決められたルールでデータをやり取りできるように作られた窓口。

APIにはいくつかの方式がありますが、今日ウェブで最も広く使われているのはREST（またはRESTful）APIです。今日はこのREST方式を基準に話します。REST自体の技術的な細部には深く入りません。ビジネスの観点で必要なのは、「決まったアドレスに、決まった形のメッセージを送ると、決まった形の答えが返ってくる」という感覚ひとつで十分です。

一つ押さえておくべき点があります。APIにはリクエストに対する答えが必ず返ってきます。その答えはまず成功か失敗かを分ける一つの数字で決着がつき、続いて詳細が添えられます。注文が正しく保存されたのか、あるいは何らかの理由で拒否されたのかが、この答えの中に収まっています。具体的な形は後ほど、ワインショップの話と一緒にもう一度見ていきます。

なぜ「通路」が必要なのか

銀行を思い浮かべてみてください。銀行の金庫にはすべてのお客様のお金が入っていますが、お客様が金庫に直接入ることはありません。代わりに窓口の行員が決められた用紙（預金・出金票）でリクエストを受け取り、本人確認を経て処理してくれます。さらに行員自身も金庫に自由に出入りするわけではありません。ルールと権限が決まっています。

データベースもまったく同じ状況です。技術的にはインターネット越しにDBへ直接つないでデータを読み書きすることは可能ですが、この扉を誰にでも開けた瞬間にビジネスは崩れます。誰かが顧客リストをそっくり持ち出せますし、誰かが商品価格を0円に書き換えられますし、誰かが在庫テーブルを丸ごと消すことすらできます。

だからこそ、データベースの前にAPIという窓口を置きます。外部からのリクエストは必ずこの窓口を通らなければなりません。窓口は三つの仕事をします。検証（リクエストの形式は合っているか）、認証と権限の確認（誰で、何ができるのか）、そして決められた範囲の操作だけを実行（お客様は自分の注文だけ照会できる、価格は絶対に書き換えられない）。外の世界と接するのはDBではなくAPIです。

ワインショップ店主のAPI

前回の最後の場面から続けていきます。ワインショップ店主はオンラインショップを開き、店舗POS・ウェブサイト・提携レストランが同時に同じデータベースを見ています。この絵が成立する理由はただ一つ、それぞれがAPIを通してのみDBにアクセスしているからです。

三者が送るリクエストを自然な言葉に置き換えるとこうなります。

• 店舗POS → 「注文を一件保存してください。」（新規書き込み）
• オンラインショップ → 「Alexさんが先月買ったワインの一覧を教えてください。」（読み取り）
• 提携レストラン → 「Château Margaux 2020の在庫を10本減らしてください。」（更新）

各リクエストは決められたアドレス（URL）に、決められた形のメッセージに包まれて届きます。メッセージ自体は通常、JSONという形式でまとまった一塊です。JSONという言葉が耳慣れなければ、Chae-wonさんが先に書いたデータにも計画が必要にざっと目を通していただくとよいでしょう。今日は「データを一塊にして規格通りに包んで送る封筒」くらいに理解しておけば十分です。

このようにアドレスとメッセージの形をあらかじめ合わせておけば、ワインショップの店主が眠っている間も注文は自動で入ってきて、DBには同じ形で積み重なっていきます。店舗スタッフが手で書き写す必要も、オンラインショップの管理者がExcelをまとめる必要もありません。ルールが作られたから自動化が可能になったのです。

では窓口がリクエストを受け取った後はどうなるでしょう。必ず答えが返ってきます。この答えはまず、人が読む文章ではなく一つの数字で決着がつきます。HTTPステータスコードと呼ばれるこの数字は数十種類ありますが、ビジネスオーナーは三つの固まりさえ知っていれば十分です。

• 200番台 — 成功：リクエストが正常に処理されました。注文が保存されたり、問い合わせたデータが一緒に返ってきます。（例：200 OK、201 Created）
• 400番台 — リクエストが誤っている：送ったメッセージ側に問題があります。必須項目が抜けている、権限がない、そのアドレスが存在しない、といったケースです。（例：400 Bad Request、401 Unauthorized、404 Not Found）
• 500番台 — サーバー側の問題：窓口の内側で異常が発生したケースです。自分のリクエストが正しくても失敗する可能性があるため、少し待って再試行するように設計します。（例：500 Internal Server Error）

この数字の後には、通常JSONブロックが一つ付いてきます。成功なら保存された注文のIDが、失敗なら何がなぜ間違っていたのかが入っています。ワインショップのAPIに「quantityフィールドが抜けた注文」を送れば、窓口は400と共に「quantityフィールドが必要です」のようなメッセージを返してくれます。この約束のおかげで、システム同士でも、人とシステムでも、同じ言葉で成功と失敗を区別できるようになります。

APIは実はどこにでもあります

ワインショップの話でなくとも、今日皆さんが使ったアプリの多くは、裏で誰かのAPIを呼んでいました。Instagramのフィードが表示されるのもサーバーのDBをAPIで読んでいるからですし、Teslaのドライバーがモバイルアプリでクルマのステータスをチェックするのも、天気アプリが今日の雨を教えてくれるのも、デリバリーアプリが店のメニューを見せてくれるのも、みな同じです。最近では冷蔵庫の注文ボタン、自動車の音声アシスタント、スマートスピーカーまで、APIの上で動いています。

ここまで話してきたAPIは「自分が必要なときに相手の窓口まで行ってリクエストを送る」やり方でした。逆に、相手のシステムの方から自分の窓口にやって来て「今こういう事が起きました」と知らせるやり方も必要です。決済が完了した瞬間に決済会社が自分のサーバーに通知を押し出してくる場面が代表的です。このやり方を区別してWebhookと呼びます。

じつはAPIとWebhookは技術的には完全に同じものです。リクエスト先のアドレスも、メッセージの形も、認証の仕方も、レスポンスコードも——どれ一つとして違いません。同じHTTP窓口の上でJSONブロックをやり取りする同じ道具であり、呼び出すコードもほとんど見分けがつきません。ではなぜ違う名前で呼ぶのでしょうか。初期のWeb APIはほとんど「自分が必要なときに相手に要求して受け取る」用途で設計されていました。時が経つにつれ「事が起きたら相手の方から先に知らせてくれる」逆方向の呼び出しが次第に増え、この逆方向を区別するために2007年頃Webhookという名前が新しく付けられました。技術が二つに分かれたのではなく、同じ道具にもう一つ役割名が加わっただけです。

ですからこう覚えておけば十分です。自分から先に呼べばAPI、相手から先に呼べばWebhook。

では、APIはどう作るのか

ここまで読むと「じゃあ自分のビジネスにもAPIを一つ作ればいいじゃないか」と自然に思われるかもしれません。ところが実際にAPIを一つ「24時間365日安全に動かす」ためには、思った以上にたくさんのピースが必要です。正直に並べてみます。

• 固有のアドレス：インターネットから呼べなければならないので、ドメインを買い、DNSを設定し、HTTPS証明書を付けます。
• 24/7のライブサーバー：一台でも止まれば売上が止まります。サーバーを複数台立て、障害を検知し、自動で復旧させる仕組みが必要です。
• コード：リクエストを受けて検証し、エラーを区別し、決められた形で応答を返し、記録を残すコードを自分で書きます。
• 認証・権限：誰がどのAPIを呼べるのかを区別する必要があります。APIキーの発行、失効、盗難キーの無効化といった運用が続きます。
• データベース連携：DBは別途インストール・運用する必要があります。バックアップ、セキュリティ、性能管理がAPIとは別に動きます。
• スケーリング・モニタリング：イベント時期にトラフィックが跳ね上がれば自動で増え、普段はコストを抑えるために減る必要があります。エラー率・応答速度・コストをリアルタイムで監視するダッシュボードも必要です。

これらすべてを一人で作らなければならないわけではありません。AWS、Google Cloud、Cloudflare、Firebase、Supabaseといったクラウドプラットフォームがそれぞれのピースを提供してくれます。ただしピースを選び、つなぎ、運用すること自体が専門領域です。ビジネスオーナーが自分でゼロから構築すると、通常はバックエンド開発者一人の数週間から数カ月の作業になります。

ここまでのまとめ

短くまとめ直します。

• APIはデータベースに安全にアクセスさせてくれる窓口です。
• 窓口は決められたアドレスと決められた形のメッセージでしかリクエストを受け付けません。
• この約束があるから、複数のシステムが同時に同じデータを見ながら動けます。
• 皆さんが眠っている間もAPIは呼ばれていて、必要な側が別のAPIを呼んでいます。自動化の実体はこの約束の上にあります。

今日すぐ試せること

前回のデータベース編では、Excel三枚でビジネスのデータ構造を描いてみました。今日はそのデータが行き来する「通路」を一度想像してみましょう。頭とAIさえあればよく、コードもサーバーも支払いも必要ありません。

Action 1. 自分のビジネスのエンドポイントを一つ描いてみる

前回分けた「人／物／取引」シートの中から一つ選び、「このシートに新しい一行が入る出来事」を定義してみてください。例：「オンラインショップに新規注文が入ったとき」。紙に三行だけ書けば十分です。

1. 出来事の名前：例）注文作成
2. 誰が送るか：例）オンラインショップ、店舗POS、お問い合わせフォーム
3. どんなデータが入るか：例）顧客番号、商品番号、数量、金額

この三行がまさにエンドポイント一つの設計です。開発者がAPIを作るときに最初に描く絵も、この水準のメモから始まります。

Action 2. AIに全体のプランをもらう

Action 1で書いたメモとともに、下のプロンプトをChatGPT、Claude、Geminiのいずれかで開いて貼り付けてみてください。

次のサービスドキュメントを参考にして、先ほど整理したエンドポイントを実際に実装するには
どの順序で始めるのが良いか、非開発者が理解できる言葉で段階的に教えてください。

https://3minapi.com/llms-full.txt

AIが返してくる答えは、おそらく「エンドポイントを一つ作って、注文一件をJSONブロック一つで送ればよい」という方向になるはずです。用語が少し耳慣れなくても慌てないでください。今日学んだ「窓口」を一つ開ける仕事だ、ということだけ覚えていれば十分です。

Action 3. 3分で初めてのAPIを体験してみる

自分でドメインを買ってサーバーを立ててDBをインストールするコースは、今日の段階ではやりすぎです。代わりに下のクイックスタートガイドをたどれば、データベース生成 → APIエンドポイント生成 → 呼び出し → DBに保存されたか確認までの全体の流れを、3分以内に手で踏んでみることができます。

ここで一つ疑問が湧くかもしれません。「APIは作ったけど、データベースはいつ作ったの？」先ほどお伝えしたとおり、本来はDBを別途インストール・運用する必要があるのですが、3Min APIではエンドポイントを作るときに入れるデータの形（フィールド）を定義すれば、それに合わせた保存領域が裏で一緒に作られます。店主の立場では窓口（API）を設計するだけで、金庫（DB）は一緒に用意される形です。「3分」という名前を使えている理由はここにあります。

👉 開発者なしでエンドポイントを作る —— クイックスタートガイド

次のピースへ

前回はデータを入れる器を見てきて、今日はその器と外の世界をつなぐ通路を見てきました。ここまで来ると残る問いは一つ。「器の間を行き来するメッセージは、実際にはどんな形をしているのか？」

次回はそのメッセージの形、つまりJSONを扱います。ワインショップの注文一件がどんな封筒に包まれてPOSからサーバーへ、サーバーからオンラインショップへ渡っていくのか、引き続きたどっていきましょう。

---

← 前回：データベースとは？エクセル利用者のための入門ガイド
→ 次回：JSONとは？非開発者の店主のための入門ガイド