前端工程師邁向後端之路 6 – 設計 RESTful API

在上一篇前端工程師邁向後端之路 5 – PostgreSQL migration：淺談 database migration ( 資料庫遷移 )？提到了為什麼需要 database migration，接下來就要開始設計 RESTful API 了！

如果對 API 的概念還不清楚的話可以參考這篇：API 是什麼 ? 最適合前端初學者的 API 概念解釋，如果想先試著從前端串 API 的話可以參考這篇：【 JavaScript瀏覽器】：實作串接 API (1) ⏤ Unsplash API。

Table of Contents

1 在沒有 RESTful API 之前

在提 RESTful API 之前我們先來說個故事：小明和小華是公司的菜雞後端工程師，兩個是同期進來的，在好不容易過了適用期之後， team leader 就提了離職，而老闆也認為沒有請新主管的必要，於是小明和小華只好相濡以沫，在沒有前輩的帶領下，自己摸索開發新功能。

有天老闆分別指派小明和小華設計兩個功能的 API，小明被分配到 user 相關的 CRUD API，小華則是被分配到 product 相關的 CRUD 的 API，兩個人都既期待又怕受傷害，期待第一個自己開發的 API 可以為公司出一份力，卻又害怕沒有人帶會把公司給搞垮，不過硬著頭皮還是得上戰場，兩個人便著手開始設計：

小明發現 http method 有一個神奇的 POST，幾乎可以處理所有的事情，就如同 div 在 HTML 中的角色，於是小明設計出來的 API 長這樣：

查詢所有使用者：POST /getAllUsers
查詢特定使用者：POST /getUser/1
新增使用者：POST /insertUser
更新使用者：POST /reviseUser/1
刪除使用者：POST /killUser/1

直接用 POST 暴力解決所有事情，樸實、無華且枯燥的解法，然後在 url 加上各種華麗的單字展現自己優秀的英文能力。

小華是個比較謹慎的工程師，他發現 http 有各種 method，每種 method 其實有它自己特殊的意義，就像你可以用 div 解決所有 html 的排版，但如果能在特定區塊使用特定的標籤，會比較好維護也會讓整個產品更精準一點，因此小華設計出來的 API 長這樣：

查詢所有產品：GET /getProducts
查詢特定產品：GET /getProduct/1
新增產品：POST /addProduct
更新產品：PUT /updateProduct/1
刪除產品：DELETE /deleteProduct/1

可以發現兩個人 API 的行為幾乎一樣，但設計出來的 API 卻是大相徑庭，為了避免在開發 API 的時候，每個人設計的風格不同導致同一個 web app 的 API 非常混亂，於是 RESTful API 成了目前設計 API 的一大「風格」，沒錯，RESTful API 只能算是設計 API 的風格，並不是明確的規範，也就是說如果公司前輩要求你要照小明這樣子設計 API 也沒有問題（只是通常就會要求整個公司統一風格，不會要求 A 功能的 API 設計照小明的， B 功能的 API 設計又照小華的）。

2. RESTful API 設計原則

照 RESTful API ( REST 全寫：Representational State Transfer ) 重新設計小明的 API，就會如下：

查詢所有使用者：GET /users
查詢特定使用者：GET /users/1
新增使用者：POST /users
更新使用者：PUT/PATCH /users/1
刪除使用者：DELETE /users/1

可以歸納一下 RESTful API 的設計原則：

2.1 url 定義完整

通常 RESTful API 的 url 定義幾乎長得一樣，只有需要對特定目標操作時會加入 params（例如上例的users/1 等等），而不會像小明和小華設計的 API，直接用 url 來描述這個 API 主要是做什麼樣的操作。

2.2 http method 定義 API 行為

可以觀察到 RESTful API 是用 http method 來定義 API 的行為，常用的 http method 如下：

GET：讀取資料
POST：新增資料
PUT：修改資料（會覆蓋所有資料）
PATCH：修改資料（只更新部分資料）
DELETE：刪除資料

至於其他更嚴格的定義可以參考：What is a REST API? – Red Hat，以 Web API 來說主要注意這邊提到的這兩點就可以了。

2.3 RESTful API 示意圖

一般來說 RESTful API 的示意圖如下（點圖可以放大）：

流程如下：

使用者對 server send http request
http server 通常會針對每個 router 定義 function，該 function 用來和資料庫溝通，因此該 function 裡面通常會寫 SQL 來對 database 做 CRUD 的操作
database server 針對收到的 SQL 操作資料

設計完 RESTful API 後，就要在 Node.js 裡實作 API 啦：前端工程師邁向後端之路 7 – 實作 Node.js RESTful API

3. 參考資料

[不是工程師] 休息(REST)式架構? 寧靜式(RESTful)的Web API是現在的潮流？
API 實作(一)：規劃 RESTful API 要注意什麼
 表現層狀態轉換- 維基百科
 What is a REST API? – Red Hat

如果覺得我的文章有幫助的話，歡迎幫我的粉專按讚哦~謝謝你！