什麼是 API？寫給非開發者店主的入門指南

大家好，我是 yeonghyeon，負責 3Min API 的開發。

在上一篇資料庫篇裡，我們收尾葡萄酒店店主的故事時，故意留下了一件事沒講。當時我說：線上商店開張之後，門市 POS、網站、合作餐廳帶來的訂單會自動堆進同一個資料庫裡 —— 但「自動」這兩個字背後的那件工具，才是今天要講的主角。它就是 API。

今天這篇文章只有一個目的。在深入學習「API」這個詞背後的複雜技術之前，先建立起 「把自己業務的流向不要只放在腦袋裡，而是整理成約定好的訊息」 的感覺。只要這份感覺有了，剩下的東西在需要時會自然跟上。您不需要任何先備知識。

什麼是 API

先從字典定義簡短看一下。維基百科 把 API（Application Programming Interface）描述為「讓應用程式彼此交換功能或資料的一套約定」。

用一句話概括：

API = 讓系統之間能依照約定好的規則交換資料的窗口。

API 有多種形式，但現在在網路上使用最廣的是 REST（或 RESTful）API。今天就以 REST 為基準來談。REST 本身的技術細節不會深入展開。從業務的角度來看，只要有這樣的感覺就夠了：「向約定好的位址，送出約定好形狀的訊息，就會得到約定好形狀的回應。」

這裡需要先點一下。API 一定會對請求給出一個回覆。這個回覆先由一個區分成功或失敗的數字定下結果，接著再補上詳細內容。訂單有沒有正確存下，或者因為什麼原因被拒絕——都裝在這個回覆裡。具體長什麼樣，稍後搭配葡萄酒店的故事再看一次。

為什麼需要「通道」

請想像一下銀行。銀行金庫裡放著每位客戶的錢，但客戶從來不會直接走進金庫。取而代之的是櫃員依照固定的表單（存提款單）接收需求，確認本人身分後再處理。就連櫃員自己也不會隨意進出金庫，規則與權限都訂得清清楚楚。

資料庫也處於同樣的情境。技術上，透過網際網路直接連上 DB 讀寫資料是可行的，但一旦把這扇門對所有人打開，生意就會崩塌。有人可以把整份顧客清單原封不動帶走，有人可以把商品價格改成 0 元，有人甚至能把整張庫存表刪掉。

所以我們在資料庫前面放一個 叫做 API 的窗口。外部來的請求一定要先通過這個窗口。窗口要做三件事：檢驗（請求的格式對不對）、身分與權限確認（您是誰、能做什麼），以及只執行約定範圍內的動作（顧客只能查詢自己的訂單，絕對不能修改價格）。真正與外部世界接觸的，是 API 而不是 DB。

葡萄酒店店主的 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 其實到處都有

就算不講葡萄酒店的故事，您今天一整天用過的 App，大多數都在背後呼叫某家的 API。Instagram 那條動態牆是伺服器端的 DB 被 API 讀出來的；Tesla 車主用行動 App 查看車況、天氣 App 告訴您今天會下雨、外送 App 顯示餐廳菜單，全部都是同一回事。最近甚至連冰箱的下單按鈕、汽車的語音助理、智慧音響，都跑在 API 之上。

到目前為止講的 API，都是「我需要的時候，走到對方窗口送出請求」這種方式。反過來，對方系統先找上我的窗口，告訴我「剛剛發生了這樣的事」的方式也是需要的。付款完成的瞬間，金流服務把通知推到我的伺服器，就是最典型的場景。這種方式另有其名，叫做 Webhook。

其實 API 和 Webhook 在技術上是完全一樣的東西。請求的位址、訊息的形狀、認證方式、回應碼——沒有一個地方不同。它們是在同一個 HTTP 窗口上交換同一塊 JSON 的同一個工具，連呼叫它們的程式碼都幾乎分不出來。那為什麼要用不同的名字？早期的 Web API 大多是為「我需要的時候去向對方要過來」這種用法設計的。時間一長，「事情一發生，對方就先來告訴我」這種反方向的呼叫越來越多，為了區分這種反方向，大約在 2007 年前後才新起了 Webhook 這個名字。技術並沒有一分為二，只是同一個工具上多了一個角色名而已。

所以只要這樣記就夠了：我先打過去叫 API，對方先打過來叫 Webhook。

那 API 到底該怎麼做

讀到這裡，您很自然會想：「那我也幫自己的生意做一個 API 不就好了？」但實際上要讓一個 API「7×24 全年安全地運作」，所需要的零件比想像中多得多。我坦白地列一下：

• 固定位址：必須能在網際網路上被呼叫，所以要買網域、設定 DNS、掛上 HTTPS 憑證。
• 7×24 的線上伺服器：只要有一台當掉，營業就停了。需要部署多台伺服器、偵測故障、自動拉起。
• 程式碼：接收請求並檢驗、區分錯誤、依約定好的形狀回傳回應、把過程記錄下來 —— 這些程式碼都要自己寫。
• 身分與權限：要能分辨誰可以呼叫哪個 API。發放 API 金鑰、讓它到期、把被盜的金鑰停用，都是持續的維運工作。
• 資料庫串接：DB 要另外安裝與維運。備份、安全、效能調校都和 API 並行運作。
• 彈性擴充與監控：活動期間流量飆升時要自動擴充，平時要縮減以節省成本。同時還要有即時盯著錯誤率、回應時間、成本的儀表板。

這些零件並不需要完全靠一個人做出來。AWS、Google Cloud、Cloudflare、Firebase、Supabase 這些雲端平台會分別提供其中的一部分。但「挑零件、串零件、維運零件」這件事本身就是一門專業。業務負責人若要從零開始搭，通常要花掉一位後端工程師數週到數個月的時間。

到目前為止的重點

簡單地再串一次：

• API 是讓您安全地存取資料庫的窗口。
• 窗口只接受送到約定好的位址、依照約定好形狀打包的請求。
• 正因為有這一層約定，多個系統才能同時看著同一份資料一起運轉。
• 您在睡覺的時候 API 一直在被呼叫，也在呼叫別人的 API。自動化的實體，就站在這些約定之上。

今天就能試試的事

上一篇資料庫篇裡，我們用三張 Excel 畫出了業務的資料結構。今天就來想像一下資料在其間來回流動的那條「通道」。只需要您的腦袋加上 AI，不需要寫程式、不需要伺服器、也不需要付費。

行動 1. 為您的業務畫出一個端點

從上一篇分出來的「人／物／交易」三張表中挑一張，為它定義一個「會讓這張表新增一列的事件」。例如：「線上商店進來一筆新訂單時」。在紙上只寫三行就夠：

1. 事件名稱：例 訂單建立
2. 由誰發出：例 線上商店、門市 POS、顧客詢問表單
3. 帶了哪些資料：例 顧客編號、商品編號、數量、金額

這三行，其實就是一個端點的設計稿。開發者在真正動手做 API 時，最先畫的那張草圖，也正是這種顆粒度的備忘錄。

行動 2. 讓 AI 給您一份整體計畫

把行動 1 的那幾行連同下面這段提示詞，一起貼進 ChatGPT、Claude、Gemini 其中任一個裡。

請參考下面這份服務文件，告訴我，要把我剛才列出的端點真的實作出來，
應該依什麼樣的順序開始，請用非開發者也能聽懂的語言一步一步說明。

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

AI 給您的回答，多半會沿著「建一個端點，把一筆訂單當作一塊 JSON 送過來」的方向。就算其中有些用語聽起來陌生也不用慌張。您只要記得一件事：這件事就是在打開我們今天講的那一扇「窗口」。

行動 3. 3 分鐘親手試一次 API

真的去買網域、開伺服器、裝資料庫的那條路，對今天這個階段來說太重了。跟著下面這份快速入門指南走一遍，就能在 3 分鐘之內親手走完建立資料庫 → 建立 API 端點 → 呼叫 → 確認資料落進 DB 的整個流程。

這裡可能會冒出一個問題：「API 建好了，可是資料庫是什麼時候建的？」前面說過，原本應該把 DB 另外安裝與維運，但在 3Min API 裡，只要您在建立端點時定義好要裝哪些欄位，配套的儲存空間就會在背後一起建好。從店主的角度來看，只要把窗口（API）設計好，金庫（DB）就一起準備妥當了。「3 分鐘」之所以能寫進名字裡，原因就在這裡。

👉 沒有開發者也能建立端點 —— 快速入門指南

下一期

上一期我們看了裝資料的容器，今天看了把這個容器與外部世界連起來的通道。走到這裡，剩下的問題只有一個：「在容器之間來回走動的那些訊息，到底長什麼樣？」

下一期我們要講的就是那些訊息的形狀，也就是 JSON。請繼續跟著葡萄酒店的一筆訂單，看看它到底被裝進哪個信封，從 POS 走到伺服器、再從伺服器走到線上商店。

---

← 上一期：什麼是資料庫？Excel 使用者的入門指南
→ 下一期：什麼是 JSON？寫給非開發者店主的入門指南