什麼是 API？給 App 製作者的白話指南
API（應用程式介面）是一種明確定義的方式，讓一套軟體向另一套軟體請求資料，或要求它執行某件事。你的 App 會以雙方約定的格式送出請求，例如「給我明天的預約」、「向這張卡收取 20 歐元」、「摘要這段文字」，而另一套系統會回傳結構化的回應。API 是 App 各部分彼此溝通的方式，也是你的 App 使用付款、電子郵件、地圖與 AI 等外部服務的方式。
用 AI 建站時，為什麼 API 很重要
幾乎每個實用的 App 都是由透過 API 溝通的部分組成的：
- 在你的 App 內部，瀏覽器中的畫面會呼叫你自己後端的 API 來載入與儲存資料。
- 在你的 App 外部，你的後端會呼叫其他公司的 API：用 Stripe 收款、用電子郵件服務寄送收據、用 AI 模型服務產生文字。
當你請 AI 建置工具「接受付款」或「加入 AI 摘要」時，它實際上是在撰寫呼叫 API 的程式碼。了解基本概念，能幫助你理解 AI 需要你提供什麼（通常是該服務的帳號與 API 金鑰）、哪裡可能出錯，以及費用會是多少。
日常生活的比喻
想像一間餐廳。你不會走進廚房自己做菜。你看菜單，用廚房能理解的方式告訴服務生你要什麼，服務生再把餐點端回來，或告訴你這道菜已經賣完了。
- 菜單就是 API 文件：列出你可以要求什麼，以及如何要求。
- 服務生就是 API：唯一約定好的方式，讓請求進來、回應出去。
- 廚房就是另一套系統：你不需要知道它內部如何運作。
- 你的點餐就是請求；端上來的餐點就是回應。
只要菜單不變，廚房就能更換烤箱、調整人手，而不會影響你。這正是 API 的真正價值：讓兩套系統可以一起運作，而彼此都不需要知道對方是如何建置的。
網頁 API 的請求如何運作
你最常遇到的大多數 API 都是透過 HTTP 運作的網頁 API，也就是你的瀏覽器使用的同一種通訊協定。每個請求都有幾個部分：
| 部分 | 是什麼 | 範例 |
|---|---|---|
| 方法（Method） | 動作的種類 | GET（讀取）、POST（建立） |
| URL／端點（Endpoint） | 你要操作之對象的位址 | https://api.example.com/bookings |
| 標頭（Headers） | 額外資訊，包括你是誰 | Authorization: Bearer <你的金鑰> |
| 內容（Body） | 建立或更新時傳送的資料 | {"name": "Lena", "time": "14:00"} |
每個回應則包含：
| 部分 | 是什麼 | 範例 |
|---|---|---|
| 狀態碼（Status code） | 以數字表示結果如何 | 200 成功、201 已建立、404 找不到 |
| 內容（Body） | 回傳的資料，通常為 JSON | {"id": 5001, "status": "confirmed"} |
JSON（JavaScript Object Notation）是一種簡單的文字格式，以大括號包住名稱與值。它是網頁 API 交換資料的標準方式。
REST：最常見的風格
REST 是設計網頁 API 時廣泛使用的慣例。每一類事物都有自己的網址，而標準方法說明你要對它做什麼。以下是預約 App 的 REST API 可能的樣子：
| 方法 | 端點 | 作用 |
|---|---|---|
GET | /api/bookings | 列出預約 |
GET | /api/bookings/5001 | 取得一筆預約 |
POST | /api/bookings | 建立新預約 |
PATCH | /api/bookings/5001 | 變更預約的部分內容，例如時間 |
DELETE | /api/bookings/5001 | 取消（刪除）預約 |
PUT 也存在，慣例上是取代整筆紀錄，而 PATCH 只會變更你傳送的欄位。
你最常看到的狀態碼：
| 代碼 | 意思 |
|---|---|
200 / 201 | 成功／已建立 |
400 | 錯誤的請求——你傳送的內容有誤或缺漏 |
401 | 未驗證——沒有有效的登入或金鑰 |
403 | 禁止存取——系統認得你，但你沒有權限執行此動作 |
404 | 找不到 |
429 | 請求過多——你已達到速率限制 |
500 | 伺服器發生錯誤 |
當你的 App 壞掉時，狀態碼通常是最快的線索。來自付款服務商的 401 通常代表 API 金鑰缺少或錯誤；429 則代表你呼叫得太頻繁。
REST 並不是唯一的風格，GraphQL 與 RPC 風格的 API 也都存在，但大多數服務與 AI 建置的後端使用的是 REST。
實例：預約確認
當客戶在美髮沙龍 App 中預約剪髮時，可能會在一、兩秒內發生數次 API 呼叫：
- 瀏覽器中的預約頁面，將服務項目、時間與客戶資料以
POST /api/bookings傳送到你的後端。 - 你的後端檢查該時段是否可用，將預約儲存到資料庫中，並回傳
201 Created。 - 你的後端使用電子郵件服務商的機密金鑰呼叫其 API：「把這封確認信寄給 lena@example.com。」
- 如果需要訂金，你的後端會請付款服務商的 API 建立結帳工作階段，並把客戶導向該處。
- 稍後，付款服務商會呼叫你的 App，告訴你付款已成功。這個反向呼叫就是 Webhook。
前兩個步驟是你自己在前端與後端之間的 API。第 3 至 5 步則是第三方 API。
常見名詞解釋
| 名詞 | 意思 |
|---|---|
| 端點（Endpoint） | API 會回應的一個特定網址。 |
| API 金鑰 | 向服務識別你的 App 的機密字串。請像對待密碼一樣小心保管。 |
| 驗證（Authentication） | 證明呼叫者是誰——透過金鑰、權杖或登入。請參閱什麼是驗證。 |
| 速率限制（Rate limit） | 在一段時間內可以發出的請求數量上限。 |
| SDK | 現成的程式庫，讓呼叫特定 API 更容易。 |
| 文件（Documentation） | 「菜單」：有哪些端點、它們接受什麼、回傳什麼。 |
| 沙盒／測試模式（Sandbox／test mode） | 服務的測試版本，不會動用真實金錢或真實資料。 |
| Webhook | 某件事發生時，另一項服務對你的 App 發出的呼叫。 |
常見錯誤與迷思
- 把秘密金鑰放在前端。 任何在瀏覽器中執行的程式碼，任何造訪的人都能看到。秘密金鑰必須留在伺服器上，保存在環境變數或機密設定中。
- 把金鑰貼到聊天中。 聊天紀錄可能會被保存。請改用建置工具提供的機密功能，並更換任何已經外洩的金鑰。
- 以為 API 是免費的。 許多 API 依請求次數或使用量收費，AI 模型 API 則依 Token 計費。請查看價格並設定花費上限。請參閱如何使用 LLM API。
- 沒有處理失敗情況。 外部服務會當機、逾時、觸及限制。請要求合理的錯誤訊息與重試機制。
- 信任瀏覽器。 你自己的 API 必須自行檢查權限。隱藏按鈕並不能阻止有人直接呼叫端點。
- 測試時使用正式金鑰。 在準備上線之前，請使用測試模式的金鑰。
向你的 AI 建置工具要求什麼
- 「這個 App 使用了哪些外部 API？每一項的費用是多少？」
- 「只從伺服器呼叫付款 API。從環境變數讀取金鑰。」
- 「列出我們 API 的每一個端點、它做什麼，以及誰被允許呼叫它。」
- 「在更新或刪除預約之前，請在伺服器上檢查登入的使用者是否擁有該預約。」
- 「如果電子郵件 API 失敗，仍然保存預約，並記錄錯誤。」
- 「目前請使用服務商的測試模式。」
Mythex 中的 API
Mythex 可以為你建置自己的 API——無論是網頁 App 的一部分，還是與前端並行運行的獨立後端（Node、Python（FastAPI）、C# 或 Java）——並撰寫呼叫外部服務的程式碼。你應該把外部服務的金鑰以專案機密的方式新增，而不是在聊天中貼上；它們在預覽中以及發布後都能被你的 App 使用。文件中提供了整合任何 API與建置 REST API 後端的範例。
常見問題
用白話來說，什麼是 API？
API（應用程式介面）是一種明確定義的方式，讓一套軟體向另一套軟體請求資料或要求它執行某件事。你的 App 以雙方約定的格式送出請求，對方系統再回傳回應，例如天氣資料、付款結果或 AI 產生的回覆。
什麼是 REST API？
REST API 是一種常見的網頁 API 風格：每一類事物（例如預約、客戶）都有自己的網址，並使用標準的 HTTP 方法。GET 用來讀取，POST 用來建立，PUT 或 PATCH 用來更新，DELETE 用來刪除。資料通常以 JSON 格式回傳。
什麼是 API 金鑰？應該放在哪裡？
API 金鑰是一串機密字串，用來向服務識別你的 App，並且通常可以讓它動用費用或存取資料。請將它保存在環境變數或專案的伺服器機密設定中，絕對不要放在會在瀏覽器中執行的程式碼裡，也不要放在公開的儲存庫中。
API 和 Webhook 有什麼區別？
使用 API 時，你的 App 會在需要時向另一項服務請求某些東西。使用 Webhook 時，則是另一項服務在某件事發生時呼叫你的 App，例如付款服務商通知你某筆付款已成功。