cover

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 吵架。

延伸閱讀