
API 就是前後端講好的「資料規格書」——你要什麼格式的資料,我就給你什麼格式。
先講結論
API(Application Programming Interface)是前後端溝通的標準介面。沒有 API,前端就得猜後端會丟什麼東西過來;有了 API,大家照著規格走,出事也知道該找誰。
燈泡跟燈座的關係
我之前跟同事解釋 API,用了一個很土的比喻但意外好懂:
你要裝燈泡,燈座是 E27 規格,你就不能硬塞一根日光燈管上去。API 就是那個燈座規格——它規定了接口長什麼樣子,資料(燈泡)必須符合規格才裝得上去。裝上去燈亮了,功能就正常運作了。
聽起來很廢?但你知道實務上有多少 bug 是因為前後端「以為對方會給什麼格式」結果完全不是那回事嗎?比你想的多太多了。
API 的回傳格式跟命名
通常 API 回傳會包含三個東西:status(成功或失敗)、message(操作訊息)、data(實際資料)。這不是什麼強制標準,但大家約定俗成就是這樣。
命名的部分,遵循 RESTful 風格的話長這樣:
GET /api/articles → 取得文章列表
POST /api/articles → 新增文章
GET /api/articles/123 → 取得特定文章
PUT /api/articles/123 → 更新特定文章
DELETE /api/articles/123 → 刪除特定文章
看到沒?URL 用名詞(articles),動作靠 HTTP Method 區分。這套邏輯搞懂之後,你看任何 API 文件都會很快進入狀況。
有沒有 API 差很多嗎?
傳統做法:後端直接把資料渲染進頁面(JSP、ASP、PHP 模板),一條龍作業。好處是簡單暴力,壞處是接手的人想翻桌——你得搞懂整個資料流才能改一個小功能。
現代做法:前後端透過 API 介面溝通,職責分離。前端出問題就看前端,後端出問題就查後端,不用再玩「這個 bug 到底是誰的」的推理遊戲。缺點就是多了一份 API 文件要維護,但我覺得這完全值得。
實務上的 API
老實說,實務上不會有人 100% 照 RESTful API 規範走。但最基本的 HTTP Methods 對應還是大家都在用的共識:
| Method | 用途 |
|---|---|
GET | 取得資料 |
POST | 新增資料 |
PUT | 更新資料 |
DELETE | 刪除資料 |
記住這四個,你就掌握了跟後端溝通的基本語言。
API 設計得好,前後端相安無事;設計得爛,每天 Slack 吵架。