如何建立 REST API：設計、安全及部署

要建立 REST API，先列出你的應用程式所管理的資源（例如用戶、訂單、預訂），為每項資源設定網址，例如 /orders 和 /orders/{id}，並用 HTTP 方法執行操作：GET 讀取、POST 建立、PATCH 更新、DELETE 刪除。回傳資料使用 JSON，並配上有意義的狀態碼；驗證每項輸入；在伺服器端要求身份驗證及逐筆記錄的權限檢查；清單需要分頁。最後為端點撰寫文件，並把 API 部署在 HTTPS 之後。

本指南涵蓋設計決定、一組示範路由、給 AI 應用程式生成器的提示，以及導致保安漏洞的常見錯誤。如果你對 API 尚不熟悉，可先閱讀什麼是 API。

何時需要 REST API

• 你的網頁前端需要向伺服器儲存及讀取資料
• 手機應用程式、合作夥伴或自動化工具需要存取你的資料
• 其他服務會向你發送事件（webhook）
• 你的前端與後端由不同團隊負責

REST 是最常見的風格，但並非唯一選擇。REST 與 GraphQL一文說明何時單一、靈活的查詢端點會更合適。

先設計：資源與路由

先寫下你的應用程式中的名詞，以及用戶會對它們做什麼操作。以一個簡單的預訂應用程式為例：

這些對應到建立、讀取、更新及刪除；參見什麼是 CRUD。值得遵循的慣例：

• 網址使用複數名詞，不含動詞：用 /bookings，不用 /getBookings。
• 只在有助釐清擁有權時才巢狀一層：例如 /bookings/{id}/notes。
• 非 CRUD 的操作可以作為子資源：POST /bookings/{id}/cancel 比一個含糊的 PATCH 更清楚。
• 欄位命名保持一致，例如所有地方都用 created_at。

狀態碼與錯誤

使用標準 HTTP 狀態碼，讓客戶端無需解析文字也能知道發生了什麼事：

錯誤回應應採用一致的 JSON 結構，例如 {"error": {"code": "slot_taken", "message": "該時段已不再可用。"}}，並且切勿在回應中包含堆疊追蹤或資料庫錯誤。

選項與取捨

逐步建立

1. 列出資源與路由，如上所述，包括每條路由可由誰呼叫。
2. 建立資料模型：在資料庫中設定你需要的欄位與關聯。
3. 先建讀取路由，然後才建建立、更新及刪除。
4. 在每次寫入時驗證輸入：使用結構驗證函式庫檢查必填欄位、類型、長度及允許值，並拒絕未知欄位。
5. 加入身份驗證，然後是逐筆記錄的授權：讀取 /bookings/42 時，必須檢查預訂 42 是否屬於呼叫者，而不只是確認有人已登入。
6. 所有清單都要分頁，並設定頁面大小上限。
7. 對登入及開銷較大的路由限制速率。參見速率限制。
8. 只有在瀏覽器需要從其他網域呼叫 API 時才設定 CORS，並明確列出那些來源。如何修復 CORS 錯誤說明你會遇到的錯誤。
9. 為每條路由撰寫文件與測試，包括失敗情況。
10. 部署：機密資料放在環境變數中，使用 HTTPS，並設有日誌及健康檢查。

給 AI 應用程式生成器的提示

建立骨架：

為預訂建立一個 REST API，路由如下：GET /api/health、GET /api/bookings（分頁，每頁最多 50 筆）、POST /api/bookings、GET /api/bookings/:id、PATCH /api/bookings/:id、DELETE /api/bookings/:id。資料存放於我們的資料庫。使用結構驗證函式庫驗證請求內容，並拒絕未知欄位。錯誤以 JSON 格式回傳，結構為 {"error": {"code", "message"}}，並使用正確的狀態碼（400、401、403、404、409）。機密資料放在環境變數中。

安全：

每條預訂路由都要求登入。在每次讀取、更新及刪除時，於伺服器端檢查該預訂是否屬於目前用戶；若不屬於，回傳 404。切勿接受請求內容中的用戶 ID 或角色。將 POST /api/bookings 限制為每位用戶每分鐘 20 次。在伺服器端記錄錯誤，但不要回傳堆疊追蹤。

文件：

為這些路由撰寫 OpenAPI 描述，以及一份簡短的 README，每條路由附上請求與回應的範例。

測試你的 API

要從前端以外測試，因為攻擊者必然會這樣做：

• 每條路由在輸入有效時，都能回傳所記錄的結構及狀態碼
• 缺少或無效的欄位會回傳 400，並附清晰的訊息
• 每條受保護路由在沒有權杖時都回傳 401
• 用戶 A 以 ID 要求用戶 B 的記錄時，回傳 404 或 403
• 清單已分頁；過大的 limit 會被限制
• 重複或衝突的建立請求回傳 409，而不是 500
• 超出速率限制時回傳 429
• 錯誤回應不含堆疊追蹤、SQL 或機密資料
• CORS 只允許你打算允許的來源

常見錯誤

• **只檢查登入，不檢查擁有權。**這是最常見的 API 漏洞：任何已登入的用戶只要更改 ID，就能讀取任何記錄。
• **信任客戶端。**請求內容中的價格、角色及用戶 ID 都可被修改。
• **回傳整行資料庫記錄。**密碼雜湊與內部欄位會外洩。應自行決定每個回應包含哪些內容。
• **不設上限的清單。**一次請求取回所有記錄，可能令整個應用程式變慢。
• **內容中夾帶錯誤訊息卻仍回傳 200 OK。**客戶端及監察工具無法判斷請求已失敗。
• 在使用 cookie 的 API 上把 CORS 設定為允許所有來源。
• 沒有健康檢查或日誌，結果要等用戶投訴才知道服務中斷。

如需更全面的上線前檢視，請參閱AI 建立應用程式的安全清單。

在 Mythex 建立 REST API

你可以要求 Mythex 把 API 作為應用程式的一部分建立，或作為獨立服務。Mythex 文件中的 REST API 後端食譜提供了起始提示：列明你的框架與路由，要求清晰的 JSON 錯誤，把機密資料放在環境變數中，並包含一個 Dockerfile。Node、Python、C#、Java 等容器後端都透過 Dockerfile 發布，Mythex 會從 Publish 處理部署（API 後端）。一個專案可以同時運行網站與 API 伺服器，並可在預覽中切換兩者。把金鑰儲存為專案機密；如果 API 需要資料庫，請在對話中提出要求。如需為 API 安排背景工作，請參閱如何執行背景工作。

常見問題