Web API | RESTful API 的優點、缺點、注意事項 | Lily程式學習筆記 | Programming Learning Notes - 點部落

2024-01-14

Web API | RESTful API 的優點、缺點、注意事項

286
0
工程師知識海
2024-05-20

內文重點：API、Web API、RESTful 注意事項 & 優點 & 缺點

上篇講完基本網路架構，這篇會細說 HTTP Request 與 HTTP Response 之間發生的事。

而這種透過網路進行交換資料的操作都是 Web API。

Web API 是一種基於 HTTP 協定下運作的 API。

首先，API 是什麼呢 ?

▊API | 應用程式介面 | Application Programming Interface

API 扮演應用程式和應用程式之間的橋樑。

API 是一種介面（Interface），開放給別人使用，只要給 Request，API 就會依據 Request 給你 Response。

API 讓我們不用管後面的邏輯內容是甚麼，只要能拿到我想要的東西就好，讓我們能專注在商業模式。

下面用Youtuber凱心琳舉的兩個例子說明API
(資料來源：凱心琳 Untyped ─ API? IPA? 應用程式介面是什麼? API種類介紹 | What is API? REST? SOAP?【電腦說人話】)

例子一、
我們在訂票系統輸入個人資料、預定的時間、信用卡資料，
按下確認鍵送出後，就會有一張票可以讓我們印出來。
而按下確認鍵後發生了什麼事？
為什麼票就這樣出來了呢？

這就是 API 的作用，按下確認鍵的瞬間，
你使用的 Browser 瀏覽器就把所有的資訊送到遙遠的一個 Server 伺服器上，
伺服器就會處理傳入的資料，然後再透過 API 把票回傳回來。

這個過程使用者感覺不到這些 Application 之間的溝通和處理過程。

而開發者開發這個網頁時，也不需要知道信用卡是怎麼被認證的，
開發者只要知道怎麼將信用卡資訊透過 API 正確的傳送到另一端，讓這個信用卡可以被驗證。

API 的好處就是可以讓開發者節省很多時間，不用去寫一些不必要的 code，
而能專注於真的要做的事情上，就是開發這個網站。

例子二、
iOS 作業系統有提供很多 API 給開發者使用，假設要做一個美顏相機，
如果今天沒有API，就要知道如何操縱 iphone 相機、操縱相機硬體，input、output 是什麼，是很複雜的。

但有了 API，開發者並不需要知道這些資訊，只需要知道怎麼使用 API，
就可以去控制手機上的相機，並開發美顏相機的 APP，
當 iOS 更新相機 API 就會連同美顏相機 APP 裡面使用到的相機 API 一起更新。

這些功能都是很多開發者需要不斷使用的，不需要每個人都做一樣的事情，API 就可以節省開發者的時間。

API 有分很多種：

作業系統裡的 API：讀取、傳輸及寫入等等電腦上的操作。
軟硬體廠商的 API：USB 與電腦交換資料。
……

而對於網頁來說就是 Web API

▊Web API

Web API 是藉由 HTTP 通訊協定，進行請求、運算、回應的 API，
透過網路（透過 URL）交換資料的操作都是 Web API。

從上圖 API 模型可以看出，
Client 端以 HTTP 通訊協定透過網路傳遞 Request 給 API，
API 把 HTTP Request 送到遙遠的一個 Server 伺服器上，
伺服器就會處理傳入的資料，再回傳 HTTP Response 給 Client 端。

而 Client 端只知道他給 API 發送 Request，API 回傳 Response，
Client 端不需要知道 API 背後做了哪些事情，重點在 Client 有拿到他想要的東西。

API 與 Client 之間傳遞的稱為「封包」（packet）。

▊封包

網路封包是網路傳送資料的最小單位。

我們可以在網頁按 F12，觀察該網頁的封包，如下圖。

封包因為不同的通訊協定，而有不同的大小。

超過限制大小，就會自動切割成數個封包進行傳遞。

點開其中一個封包，可以看到如下圖。

從上圖，可以看到一個封包由兩部分組成：標頭Header和裝載Payload。

Header 標頭：
封包的屬性被詳細地定義在標頭中。
包括所使用的通訊協定、來源&目的地的IP位址、來源&目的地的通訊埠…等欄位。
網路封包的結構、欄位資料，會依採用的通訊協定決定。
常見的欄位還有：
- URL
- HTTP Method
- Status Code
- Content Type
Payload 裝載：
就是實際輸入的資料。
例如：在客戶系統搜尋時，會輸入客戶姓名、負責業務，就會放入 Payload。

在 HTTP 協議中 Request 和 Response 分別組成如下：

而這些項目常用 RESTful 的風格來撰寫，RESTful API 是 Web API 的一種撰寫風格。

▊REST | 表現層狀態傳輸 | Representational State Transfer

REST 是一種 API 設計風格（並非一種標準），
是目前最常見描述 API 的方式。

Representational 表現層，指的是「資源」（Resource）的表現層。
「資源」，就是網路上的一個實體（例如:文字、圖片、音樂、影片、服務），
使用URI 指向資源，所有資源都會有一個獨一無二的URI（Uniform Resource Identifier）。
( 參考 ─ 前端小字典三十天【每日一字】– REST )

Representation 反應出 given resource 的過去、現在、期望的資訊狀態。( Representation )

「現在的狀態」：例如，用GET /users/123取得的資源，就是代表著現在的狀態。
「期望的狀態」：例如，用PUT /users/123更新資源，代表資源「現在的狀態」被更新，而「預期的狀態」就會變成「現在的狀態」。
「過去的狀態」：例如，用DELETE /users/123 刪除資源後，再用 GET 取得「現在的狀態」會找不到資源（404），被刪除的資源就是「過去的狀態」。
(參考 ─ 找不到資料要回 404 還是 200？)

從上面可以看出是透過 HTTP Method（GET、POST、PUT、DELETE…），
來實現狀態傳輸 State Transfer。

Header 中的 Content-type，就是 Representation 資源呈現的方法、格式像是 JSON，XML，YAML ......，
而每個回傳代表的都是資源當前狀態。

所以 Representational State Transfer 就是表現資源狀態的傳輸。

▊什麼是 RESTful ?

使用 REST風格所設計出來的 API 可稱之為RESTful API，
表示API 在設計上遵循著REST的原則與理念。

一般的 API 可能長得像這樣 ⬇

/api/get_file/ ( 得到檔案 )
/api/upload_file/ ( 新增檔案 )
/api/update_file/ ( 更新檔案 )
/api/delete_file/ ( 刪除檔案 )

RESTful API 則長得像這樣 ⬇

/api/files/ ( GET → 得到檔案 )
/api/files/ ( POST → 新增檔案 )
/api/files/ ( PUT → 更新檔案)
/api/files/ ( DELETE → 刪除檔案 )

REST 概念就是藉由操作【動詞】不同的 URL【名詞】達成不同的資料呈現方式【表現】。

如下圖 RESTful-Triangle ，說明 RESTful API 主要由三種元件組成：

Nouns 名詞：
定義資源，讓 Resources (資源) 有唯一的識別。
在 HTTP 中我們用 URI 來標示資源，例如：http://car.com/cars/{carName}。
每個資源在網路上都會有唯一的位置，就如每戶人家都有唯一的地址一樣。
Verbs 動詞：
對資源要做的動作。
在 HTTP 中使用 HTTP Methods（GET、POST、PUT、DELETE…），
對資源做「取得」、「新增」、「修改」、「刪除」的操作。
Content Types 資源呈現方式：
資源呈現的方式，像是 JSON，XML，YAML……
是 Header 中的 Content-type，就是 REST 的 Representation 。

RESTful 是建立在 HTTP 協定之上的設計模式。

使用HTTP Method後，就能擁有清楚、簡短的 URI。

因此 RESTful API 讓我們有可讀性強的網頁網址 URL 來指定並操作 Resource。
舉例：

GET /api/files/       //得到所有檔案
GET /api/files/1/     //得到檔案 ID 為 1 的檔案
POST /api/files/      //新增一個檔案
PUT /api/files/1/     //更新 ID 為 1 的檔案
PATCH /api/files/1/   //更新 ID 為 1 的部分檔案內容
DELETE /api/files/1/  //刪除 ID 為 1 的檔案

上面做的事情就是 CRUD：
Create（新增）、 Read（讀取）、 Update（更新）、 Delete（刪除）

▊HTTP Method | HTTP方法

HTTP Method	說明	安全特性	安全特性說明
GET	回覆請求資料	Safe	不會改變資源狀態
POST	創建資源或其他應用	Unsafe	重複一樣的新增可能會產生多筆相同的資源
PUT	取代現有資源	Idempotent	重複一樣的取代不會產生多個重複的資源
PATCH	更新資源	Unsafe	重複一樣的更新可能會讓資源有重複的屬性
DELETE	刪除資源	Idempotent	重覆一樣的刪除不會改變資源已刪除的狀態

▊URI V.S. URL

URI，Uniform Resource Identifier，統一資源標識

用來標識網際網路中的資源
資源像是 HTML檔案、程式碼、影片、圖片等等都適用 URI 來標識

URI 就是標記網路上的資源，其中又包含 URN 和 URL

URL，Uniform Resource Link，統一資源連結，幫資源定位（地址）
URN，Uniform Resource Name，統一資源名稱，幫資源取名字

▊實踐RESTful API 注意事項

API 的 URI 應始終為小寫。
設計 API 時請勿使用駝峰命名法。
使用連字符 " - " 而不是底線分隔多個單字。
不要縮寫，URI 中的單字要使用完整且有意義的形式。
如果API 接受變數，則應使用駝峰式命名法表示它，並括在一組大括號 { } 內。
e.g., https://localhost:2024/api/co-agents?emailAdress={emailAdress}&firstName={firstName}
使用正斜線表示層次關係。
資源名稱使用名詞，而不是動詞。
資源名稱如下面範例 URL中的 orders
應該使用複數名詞來表示集合。

範例：

▊RESTful API 優點 & 缺點

優點

使用URL和HTTP Method做到資源和操作分離。

✔更好的管理資源
✔使用者可以快速的了解 API，省去不必要的溝通，
如果熟悉 HTTP Method 的開發者，甚至可以不用看 API文件就開始串接資料。

缺點

REST 只是撰寫的風格，並沒有辦法提升安全性，
因此仍須設置安全措施，例如：使用 SSL/TLS 傳輸層安全性協定，以建立加密網路連線。
REST 因為遵循 Stateless (無狀態)，所以無法在 Server 端做維護，責任都在 Client 端發送的 Request。

恭喜你讀完了🥳

讓我們試著回答下面這些問題，確認自己是否真的理解了！

What do you understand by RESTful API ?
- REST，Resource Reprsentation State Transfer，資源具象狀態傳輸。
  Resource 資源，就是網路上的一個實體（例如:文字、圖片、音樂、影片、服務）。並用 URI 來標示資源。
  Representation，Header 中的 Content-type，就是 Representation 資源呈現的方法、格式像是 JSON，XML，YAML ......，
  而每個回傳代表的都是資源當前狀態。
  State Transfer 狀態傳輸，透過 HTTP Method 來傳輸狀態。
- RESTful API 是遵循 REST 架構的 Web API。
- 基於 HTTP 協議，Client 端通過網頁瀏覽器發出 Request Header、Request Body 去訪問 Server，
  Server 回傳 Response Body、Status code 給 Client 端。
- RESTful 讓 Web API 輕巧、易於維護、具有可擴展性、支援使用不同程式語言開發的各應用程式間的通訊。
- 以HTTP為基礎，透過用 HTTP Method 使 URL 可以清楚簡短。
What is a REST Resource ?
- Resource 資源類似於物件導向程式設計世界中的物件。
  REST的Resource，包含：文字檔案、圖片、程式碼、HTML …或任何動態資料，都是 Web API 傳輸的資源。
- 這些網路資源都通過統一資源識別（URI）來標示。
What is URI ?
- URI：Uniform Resource Identifier 統一資源識別
  
  用來標記網路資源，資源包含 HTML 檔案、程式碼、影片、圖片…，都適用URI來標示。
- URI，又包含URL、URN：
  - URL：Uniform Resource Link 統一資源連結，幫資源定位(地址)，尋找某資源的方式
  - URN：Uniform Resource Name 統一資源名稱，幫資源取名(名字)，定義某資源的身分
What are the features of RESTful Web Services ?
- 建立在 Client - Server 的模型上
- 使用 HTTP 協議
- Client 端與 Server 端之間的通訊媒介稱為 Messaging
- 資源可以通過統一資源識別（URI）來存取、標示。
- 遵循無狀態（Stateless）的概念，每一個 Request 必須包含所有需要的資訊，而不需依賴 Sever 中的狀態。
- 使用快取（Caching）的概念，減少同樣的 Request 呼叫 Server 的次數。

What is the concept of statelessness in REST ?
1. 了解 Stateless 無狀態前先了解 Stateful 有狀態。
  Stateful 是假設你要準備要登入一個網站，你輸入了你的帳號及密碼。
  如果網站的伺服器將你的資料存在後台，
  每次登入時就會利用儲存的資料來驗證你的身分的話，
  我們可以說這個登入服務就是有狀態的。
  當你使用該服務時，對你每個操作都會參考已經預先存好的狀態(這邊指使用者資料)，
  當你請求一個帳戶資料的頁面時，
  伺服器會做兩件事: (1) 誰在請求? (2) 根據請求者的 ID，要秀出什麼頁面給他們看?
  像這樣有狀態的網路服務，對每個 GET 請求的回覆都必須要依賴儲存在伺服器裡的狀態，
  如果沒有這個狀態就無法正確的回傳資料。
2. Stateless 無狀態
  假設我們創建了一筆資料，這個資料並不依賴於任何的狀態。
  意思就是我們不需要等待伺服器來確認我們的操作是否被正確地處理了。
  像是 REST 就是一個無狀態的設計概念，必須在 Client 端發出 Request 時，
  將必要資料都包含在 Request 裡，就不需要依賴Sever 裡的狀態。
What are HTTP Status codes ?
- 用 Status codes 狀態碼代表 Request 經過處理後的狀態：
  2XX 開頭代表成功、
  3XX 開頭代表轉址、
  4XX 開頭代表使用者的錯誤、
  5XX 開頭代表系統錯誤。
What are the HTTP Methods ?
- HTTP協議下的方法，包括：
  Get 查詢、Post 新增、Patch 部分更新、Put 更新、Delete 刪除。
Can you tell the disadvantages of RESTful web services ?
- 因為遵循 Stateless，所以無法在 Server 端做維護，責任都在 Client 端發送的 Request。
- REST 只是撰寫的風格，並沒有辦法提升安全性，
  因此仍須設置安全措施，例如：使用 SSL/TLS 傳輸層安全性協定，以建立加密網路連線。
Define Messaging in terms of RESTful web services ?
- 遵循 RESTful，並以 HTTP 的形式發送 Request，並以 HTTP 的形式回傳 Response，
  這種訊息的傳遞就稱為 Messaging。