為什麼你的 API 會被其他工程師抱怨？

在前面的章節，我們把 API 比喻成「餐廳的服務生」。前端工程師（客人）向服務生點餐，後端工程師（廚房）透過服務生把餐點送出來。想像一下，如果你去一家餐廳，菜單上寫著：

A 餐：拿豬肉給客人()
B 餐：讓客人給我們雞肉()
C 餐：把那盤青菜換掉()

你一定會覺得這家餐廳莫名其妙。在程式世界裡，如果你自己隨便亂取 API 的網址名稱（例如：/getTheDataNow, /deleteUser123），當其他前端工程師或別家公司要串接你的系統時，他們也會覺得你莫名其妙。

為了讓全世界的服務生跟客人都能用同一種語言溝通，軟體界發明了一套標準的「API 命名與設計法規」，叫做 RESTful API。如果你想要在接案市場或是大公司生存，寫出符合 RESTful 標準的 API 是絕對必備的基本功。

RESTful API 的兩大核心：動詞 (Method) 與名詞 (Resource)

RESTful API 的設計精神非常簡單：用 HTTP 動詞來表示「動作」，用網址來表示「東西 (資源)」。你絕對不應該在網址裡面寫出動詞！

核心一：四大 HTTP 動詞 (CRUD)

在上一章我們學過 GET 跟 POST，其實在標準的 RESTful 世界裡，總共有四個最常用的動作，剛好對應到資料庫的增刪改查 (CRUD)：

GET (讀取/查)：我要看這個東西。
POST (新增/增)：我要創造一個新的東西。
PUT / PATCH (修改/改)：我要更新這個東西的資料。
DELETE (刪除/刪)：我要把這個東西消滅。

核心二：網址只放名詞 (而且要是複數)

假設我們今天在開發一個「書店系統」，我們要管理「書本 (books)」。

❌ 錯誤的 (非 RESTful) API 設計：

/getAllBooks (動詞混在網址裡，很糟)
/createNewBook
/deleteBook?id=5
/updateBookPrice

✅ 正確的 RESTful API 設計：

GET /books (列出所有書本)
GET /books/5 (只看 ID 是 5 的那本書的詳細資料)
POST /books (新增一本書，資料放在 Body 裡)
PUT /books/5 (修改 ID 是 5 的書本資料)
DELETE /books/5 (刪除 ID 是 5 的那本書)

你看！網址永遠都只有 /books，非常乾淨整潔。我們是靠前面的「動詞」來告訴伺服器我們到底要對這些書做什麼事。

為什麼 RESTful 這麼重要？因為它能做到「盲猜」！

當你嚴格遵守 RESTful 規範時，你的 API 就擁有了一種超能力：可預測性。

假設今天你要去串接 Facebook 的 API，你想取得使用者的貼文 (posts)。就算你還沒有去看 Facebook 的官方文件，一個有經驗的工程師也能直接「盲猜」出正確的網址：一定是 GET /users/{user_id}/posts。

你想刪除某篇留言 (comments) 呢？一定是 DELETE /comments/{comment_id}。

這種全世界共通的默契，極大地降低了工程師之間溝通的成本，也讓你的系統看起來極度專業。

Vibe Prompt 實戰：用 AI 秒生標準規格書

對於非本科系的新手來說，一開始要自己設計出完美的 RESTful 網址可能會有點卡卡的。沒關係，這正是 Vibe Coding 派上用場的時候。我們不需要自己設計，我們請 AI 幫我們規劃。

【RESTful API 規劃 Prompt】 我正在開發一個「電商購物車系統」。請幫我設計一組符合嚴格 RESTful 規範的 API 列表。我需要管理兩個資源：

products (商品目錄)

cart_items (購物車內的商品)

請列出這兩個資源的 CRUD (增刪改查) 對應的：

HTTP Method (動詞)

URL (網址路徑)

簡短說明這個 API 的用途請用清楚的 Markdown 表格呈現。

AI 產出的專業 API 規格書 (節錄)：

| 資源 | HTTP Method | URL Path | 用途說明 | | :--- | :--- | :--- | :--- | | 商品 | GET | /products | 取得所有商品的列表 | | 商品 | GET | /products/{id} | 取得單一商品的詳細資訊 | | 商品 | POST | /products | (後台用) 新增一樣商品 | | 購物車| POST | /cart_items | 將商品加入購物車 | | 購物車| DELETE | /cart_items/{id} | 將商品從購物車中移除 |

只要你拿著這張表去跟前端工程師開會，他們一定會覺得你是一個經驗豐富的架構師！

在下一章中，我們將探討 API 世界中最危險、但也最核心的議題：認證與授權 (Authentication & Authorization)。如果你的 API 沒有鎖門，那全世界都能隨便刪除你的資料！

🎁 [VIP 專屬加碼] API 進階除錯術與 Webhook 逆向工程

在接案市場上，最賺錢的案子通常不是「從零做一個網站」，而是「把 A 系統跟 B 系統串接起來」。例如：客戶想把他們家的 ERP 系統，跟 LINE 官方帳號串接。這時候，API 與 Webhook 的觀念就是你接下這種 10 萬元起跳案子的核心武器。

1. 學會看懂 API 錯誤訊息 (不再瞎子摸象)

當你用 Postman 打 API，卻收到紅色的 Error 時，不要急著去問 Cursor。請先學會自己判讀狀態碼：

401 Unauthorized：90% 是你的 Headers 裡面忘記帶 Bearer Token，或是 Token 已經過期了。去重新登入拿一組新的！
403 Forbidden：你有 Token，但你的權限不夠。例如你是一般會員，卻試圖呼叫 /api/admin/delete_user。
422 Unprocessable Entity：你送過去的資料格式錯了。例如後端要的是 {"age": 25}，你卻送了字串 {"age": "二十五"}。仔細檢查你的 JSON Body！
CORS Error (前端專屬噩夢)：當你在瀏覽器呼叫別人的 API，卻看到紅色的 CORS 錯誤。這代表對方的伺服器沒有允許你的網域存取。解法：在後端加上 cors 套件，或是透過 Next.js 的 Route Handlers 做一層中繼代理 (Proxy)。

2. 什麼是 Webhook？(API 的反向操作)

傳統的 API 是「你主動去問別人」。例如：你每 5 分鐘打一次 /api/check-payment 問綠界科技：「這筆訂單客人付款了嗎？」這非常浪費伺服器資源。

Webhook 是「別人主動來通知你」。你寫一支 API (例如 /api/webhook/ecpay)，然後把這個網址交給綠界。當客人付款成功的瞬間，綠界會「主動」打你的這支 API，告訴你：「付款成功了！訂單號碼是 12345」。這就是所謂的 Webhook (網路鉤子)，它是現代 SaaS 服務之間最主流的溝通方式 (包含 LINE Bot、Stripe、綠界、GitHub Actions 全部都依賴 Webhook)。

3. Vibe Coding 實戰：一鍵產生 Webhook 接收器

在開發 Webhook 時，因為是「別人打給你」，所以你沒辦法用 Postman 自己測。這時候，強大的 Cursor 再次發揮作用。

✅ Vibe Prompt 示範：

「我需要寫一支 Node.js 路由來接收 LINE 官方帳號的 Webhook 訊息。

路徑為 POST /api/webhook/line。

請幫我寫好驗證 LINE Signature 的安全防護邏輯，確保這個請求真的是從 LINE 官方發出來的。

如果收到使用者的文字訊息，請先使用 console.log 將內容印出來即可。

最後，務必回傳 200 OK 給 LINE 伺服器，否則 LINE 會判定發送失敗。」

有了這個觀念，你已經具備了打通全世界所有 SaaS 系統任督二脈的能力。準備好成為企業眼中的系統整合大師了嗎？