淺談 API 與 RESTful API

前言

RESTful API 可以說是非常常聽到的一個名詞，身為前端開發者來講更是容易接觸到，那什麼是 RESTful API 呢？這一篇就讓我們來聊聊什麼是 RESTful API 吧。

What is an API？

一開始我想聊一下什麼是 API，API 全名是 Application Programming Interface (中文又譯應用程式介面)，那什麼是 API 呢？

你試著思考一下今天你在使用 Google Maps 的時候是不是只需要輸入你要到達的地點，然後 Google Map 就會顯示出你要的路線或者地點，接下來再思考一下，你在搜尋一些文章、問題以及知識時都會在搜尋頁面上的輸入框輸入關鍵字，然後按下「搜尋」這個按鈕，屆時畫面就會出現搜尋的結果。

其實這些功能的呈現都是依賴著 API 完成，反正你現在去搜尋「wiki 什麼是 API」這個關鍵字，應該會看到維基百科這一篇解釋：

應用程式介面（英語：Application Programming Interface），縮寫為API，是一種計算介面，它定義多個軟體中介之間的互動，以及可以進行的呼叫（call）或請求（request）的種類，如何進行呼叫或發出請求，應使用的資料格式，應遵循的慣例等。它還可以提供擴充機制，以便使用者可以通過各種方式對現有功能進行不同程度的擴充。一個API可以是完全客製化的，針對某個組件的，也可以是基於行業標準設計的以確保互操作性。通過資訊隱藏，API實現了模組化編程，從而允許使用者實現獨立地使用介面。

好吧，看完上面的描述你大概還是會問「到底什麼是 API，前面講一推我還是看不懂。」

我們換個方式來形容一下什麼是 API 吧。

我在之前的某一篇文章(淺談 SPA、CSR、SSR、MPA、SSG 專有名詞)有一段舉例是以下

今天我(使用者)想要看哥吉拉的描述，但是這邊畫家很窮，每一次想看什麼，我都必須提供一張白紙，並附上一張信件的內容 (Request) 描述，舉例來講：畫家你好，我希望可以請你幫忙準備畫一張哥吉拉的畫像。
接下來我們就會請帥氣郵差先生/小姐(網路)幫我們將信件內容交給畫家(伺服器)，接下來畫家就會依據我們信件內容開始準備畫筆並在我們一起寄給他的白紙繪畫上哥吉拉的畫像，最後繪畫完畢之後，畫家會再請郵差將畫好的繪畫一起寄回去給我來觀看。

其實概念就非常雷同，我們今天如果要寫信給朋友，就會請郵差依照我們提供的地址寄送給朋友，然後朋友就會依據信件內容回覆給我們。

接下來讓我們套入程式的角度來看

• 使用者(我)
• 郵差(API)
• 朋友(主機)

感覺應該有比較釐清一點了吧？所以簡單來講 API 本身就是一個你請求它做什麼事情，然後系統會依照你請求的回應給你什麼東西。

我相信看完前面之後，你在看這一部影片會更能理解「什麼是 API」，

RESTful API

那麼 RESTful API 又是什麼呢？簡單來講它是一個 API 設計風格，早期我們在開發 API 的時候可能會是像以下這樣子來命名

• getUserAll - 取得全部使用者
• getUser/1 - 取得特定使用者
• createUser - 新增使用者
• editUser/1 - 編輯特定使用者
• deleteUser/1 - 刪除特定使用者

看起來是相當直覺沒有錯，但如果是採用 RESTful API 的話，它則會長得像是以下

• [Get] /users - 取得全部使用者
• [Get] /user/1 - 取得特定使用者
• [Post] /user - 新增使用者
• [Put] /user/1 - 編輯特定使用者
• [Delete] /user/1 - 刪除特定使用者

我們可以看到 RESTful API 風格的設計方式具有以下優勢

• 簡潔
• 符合 HTTP Methods

除此之外這邊也要注意一下 RESTful API 的一些設計重點

• 普通的資源會傾向使用復數(加上 s)
  • 如：/users or /courses，但我也有看過使用單數就是了。
• 唯一(單一)資源使用單數
  • 如：/user/1 or /course/1，例如你要編輯單一使用者、單一課程這類就會建議使用單數。
• 命名盡可能都是採用小寫，若要區分的話可以使用 - or _
  • 但我個人是比較喜歡使用 -，如 /my-course。
• 盡可能透過該 API 命名就可以知道用途
  • 如果你取名為 /products 但回傳的卻是使用者資料那也很奇怪吧？
  • 請不要隨意命名，如：/abc 這類型無意義的命名。
  • 假設今天是電商產品 API 的話，可以像這樣命名 [Get] /shopping/products。
• 適當的提供 HTTP Code，這一區塊建議可詳見 wiki。
• 盡可能在 API 設計上要考慮到可擴充與彈性
  • 舉例來講，通常我們可能會遇到 API 的升級，所以我自己在命名上就會用 v1、v2 作為差異區分，如：[Get] /v1/shopping/products、[Put] /v1/shopping/product/1。

因此採用 RESTful API 風格設計是為了盡可能統一且可擴充，對於開發者來講也可以透過該 API 很直覺的理解到用途，所以如果能加減了解 RESTful API 的設計方式，其實是可以幫助到自己的。

參考文獻

• 什麼是 API
• 表現層狀態轉換
• HTTP 請求方法
• HTTP狀態碼