RESTful API

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

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

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

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 的示意圖如下(點圖可以放大):

RESTful API

流程如下:

  1. 使用者對 server send http request
  2. http server 通常會針對每個 router 定義 function,該 function 用來和資料庫溝通,因此該 function 裡面通常會寫 SQL 來對 database 做 CRUD 的操作
  3. 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

看完這篇文章是不是想換工作了呢(咦?那就千萬別錯過 2024 職涯博覽會!想換工作的,有機會在博覽會遇見更好的另一半,不想換工作的,有機會在博覽會遇見更好的工作!趕快點擊下面的 banner,拯救你的人生!!!https://s.yourator.co/jimmy

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

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top