什麼是 API？為應用程式建造者而寫嘅淺白指南
API（應用程式介面）係一種既定方法，令一件軟件可以向另一件軟件要求資料，或者令佢做某啲嘢。你嘅應用程式會用約定好嘅格式發出請求——「俾我聽日嘅預約」、「向呢張卡收 €20」、「幫我總結呢段文字」——然後另一個系統返回結構化嘅回覆。API 係應用程式各部分之間互相溝通嘅方式，亦係你嘅應用程式使用外部服務（例如付款、電郵、地圖同 AI）嘅方式。
點解 API 喺用 AI 建造嘢時重要
幾乎所有有用嘅應用程式都係由透過 API 溝通嘅部件組成：
- 喺你嘅應用程式入面，瀏覽器中嘅畫面會呼叫你自己後端嘅 API 去載入同儲存資料。
- 喺你嘅應用程式外面，你嘅後端會呼叫其他公司嘅 API：用 Stripe 收款，用電郵服務商發收據，用 AI 模型服務商生成文字。
當你叫 AI 建造工具「加入收款」或者「加一個 AI 摘要」，佢實際上係喺寫代碼去呼叫 API。明白基本概念，有助你了解 AI 需要你提供咩（通常係該服務嘅帳戶同一個 API 金鑰）、可能喺邊度出錯，以及會有幾多成本。
日常比喻
諗吓一間餐廳。你唔會走入廚房自己煮。你睇吓餐牌，用廚房聽得明嘅方式話畀侍應知你想要咩，然後侍應會帶返你嘅食物——或者話畀你知嗰道菜已經售罄。
- 餐牌就係 API 文件：列出你可以要求咩，以及點樣要求。
- 侍應就係 API：請求入去、回覆出嚟嘅那個約定好嘅途徑。
- 廚房就係另一個系統：你唔需要知道佢入面點運作。
- 你嘅點餐係請求；上枱嘅餐係回覆。
只要餐牌唔變，廚房就可以更換爐具同人手，而你唔受影響。呢個就係 API 嘅真正價值：令兩個系統可以合作，而且兩邊都唔需要知道對方點樣建造。
Web API 請求點運作
你會遇到嘅大部分 API 都係透過 HTTP 運作嘅 web API，即係你瀏覽器用嘅同一個協議。每個請求都有幾個部分：
| 部分 | 係咩 | 例子 |
|---|---|---|
| 方法（Method） | 動作類型 | GET（讀取）、POST（建立） |
| URL／端點（endpoint） | 你要操作嘅對象嘅地址 | https://api.example.com/bookings |
| 標頭（Headers） | 額外資訊，包括你係邊個 | Authorization: Bearer <your key> |
| 主體（Body） | 你傳送嘅資料，用於建立同更新 | {"name": "Lena", "time": "14:00"} |
每個回覆都有：
| 部分 | 係咩 | 例子 |
|---|---|---|
| 狀態碼（Status code） | 一個數字，表示結果如何 | 200 成功、201 已建立、404 搵唔到 |
| 主體（Body） | 返回嘅資料，通常係 JSON | {"id": 5001, "status": "confirmed"} |
JSON（JavaScript Object Notation）係一種簡單嘅文字格式，用大括號入面嘅名稱同數值表達資料。佢係 web API 交換資料嘅標準方式。
REST：最常見嘅風格
REST 係一套廣泛使用嘅 web API 設計慣例。每類事物有自己嘅網址，而標準方法就講明你對佢做緊咩。以下係一個預約應用程式嘅 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 | 伺服器出錯 |
當你嘅應用程式壞咗，狀態碼通常係最快嘅線索。一個付款服務商返回 401，通常代表缺少或者錯誤嘅 API 金鑰；而 429 就代表你呼叫得太密。
REST 唔係唯一嘅風格——GraphQL 同 RPC 式 API 都存在——但大部分服務同 AI 建造嘅後端用嘅都係 REST。
實例：預約確認
當客戶喺髮型屋應用程式預約一個剪髮時段，幾秒之內可能會發生數個 API 呼叫：
- 瀏覽器中嘅預約頁面會將服務、時間同客戶資料，用
POST /api/bookings傳送去你嘅後端。 - 你嘅後端檢查時段係咪空閒，喺資料庫儲存預約，然後返回
201 Created。 - 你嘅後端用佢嘅 secret 金鑰呼叫電郵服務商嘅 API：「將呢封確認電郵發送畀 lena@example.com。」
- 如果需要訂金，你嘅後端會向付款服務商嘅 API 要求建立結賬會話，並將客戶送去嗰度。
- 之後，付款服務商會呼叫你嘅應用程式，話畀你知付款已成功。嗰個反向呼叫就係一個 webhook。
頭兩步係你自己喺前端同後端之間嘅 API。第 3 至 5 步係第三方 API。
常見術語解釋
| 術語 | 意思 |
|---|---|
| 端點（Endpoint） | API 會回應嘅一個特定網址。 |
| API 金鑰（API key） | 用嚟向服務識別你應用程式嘅 secret 字串。要當成密碼一樣保護。 |
| 驗證（Authentication） | 證明邊個正在呼叫——用金鑰、token 或者登入。見什麼是驗證。 |
| 速率限制（Rate limit） | 規定你喺某段時間內可以發出幾多請求。 |
| SDK | 一個現成嘅代碼函式庫，令呼叫某個特定 API 更容易。 |
| 文件（Documentation） | 「餐牌」：有咩端點、接受咩、返回咩。 |
| 沙盒／測試模式（Sandbox / test mode） | 服務嘅測試版本，唔涉及真錢或者真實資料。 |
| Webhook | 喺事件發生時，由另一個服務呼叫入你嘅應用程式。 |
常見錯誤同誤解
- 將 secret 金鑰放喺前端。 任何喺瀏覽器執行嘅代碼，任何訪客都睇得到。Secret 金鑰必須留喺伺服器上，放喺環境變數或者 secrets入面。
- 將金鑰貼入聊天。 聊天紀錄可能會被儲存。改用建造工具嘅 secrets 功能，並為任何已經洩露嘅金鑰更換新值。
- 以為 API 免費。 好多 API 按請求次數或者用量收費——AI 模型 API 按 token 收費。要查清價格，並設定消費上限。見點樣使用 LLM API。
- 唔處理失敗情況。 外部服務會停頓、超時同達到限制。要求建造工具提供合理嘅錯誤訊息同重試機制。
- 信任瀏覽器。 你自己嘅 API 必須自己檢查權限。隱藏一個按鈕並唔可以阻止有人直接呼叫端點。
- 測試時用正式金鑰。 準備上線之前，都要用測試模式金鑰。
要求你嘅 AI 建造工具做咩
- 「呢個應用程式用咗邊啲外部 API？每個要收幾多錢？」
- 「只喺伺服器上呼叫付款 API。從環境變數讀取金鑰。」
- 「列出我哋 API 嘅每個端點、佢做咩，以及邊啲人被允許呼叫佢。」
- 「喺伺服器上檢查登入嘅用戶確實擁有該預約，然後先至更新或者刪除。」
- 「如果電郵 API 失敗，仍然儲存預約，並記錄錯誤。」
- 「暫時用服務商嘅測試模式。」
Mythex 中嘅 API
Mythex 可以建造你自己嘅 API——無論係一個 web 應用程式嘅一部分，定係一個獨立嘅後端（用 Node、Python（FastAPI）、C# 或 Java），同你嘅前端並行運行——並撰寫呼叫外部服務嘅代碼。你將佢哋嘅金鑰加入項目 secrets，而唔係喺聊天入面貼出，而且應用程式喺預覽同發佈之後都可以用到。docs 有整合任何 API 同建立 REST API 後端 嘅食譜。
常見問題
簡單嚟講，什麼是 API？
API（應用程式介面）係一種既定方法，令一件軟件可以向另一件軟件要求資料，或者要求佢做某啲嘢。你嘅應用程式會用約定好嘅格式發出請求，然後另一個系統返回回覆——例如天氣資料、付款結果或者 AI 生成嘅回覆。
什麼是 REST API？
REST API 係一種常見嘅網頁 API 風格：每類事物（預約、客戶）都有一個網址，你用標準嘅 HTTP 方法——GET 用嚟讀取、POST 用嚟建立、PUT 或 PATCH 用嚟更新、DELETE 用嚟刪除。資料通常以 JSON 形式返回。
API 金鑰係咩？應該放喺邊度？
API 金鑰係一串用嚟向某個服務識別你應用程式嘅 secret 字串，而且通常可以令佢花錢或者存取資料。要將佢放喺環境變數或者你項目伺服器上嘅 secrets 入面，唔可以放喺瀏覽器會執行嘅代碼入面，亦唔可以放喺公開嘅儲存庫入面。
API 同 webhook 有咩分別？
用 API，你嘅應用程式會喺需要嘅時候向另一個服務要求某啲嘢。用 webhook，就係另一個服務喺事件發生時呼叫你嘅應用程式——例如付款服務商通知你付款已成功。