後端框架與API 開發(6-1) - Web API

※ 什麼是Web API

API 就是後端開出來讓前端來用的介面，讓前端與後端可以溝通。

API流程：

• 終端使用者用任何一種裝置進入瀏覽器。
• 瀏覽器透過 API 向後端發出請求，請求查詢或修改資料。
• 後端透過 API 收到前端的請求後，取得資料並回應給前端。
• 前端渲染畫面，終端使用者看到頁面。

※ API 溝通文件：

API 文件的主要目標是使開發人員能夠有效地使用 API，並為他們提供必要的訊息，以實現應用程序的相互操作性和功能。

 API 文件可能包含的內容如下：

1. API 描述：對API的簡要概述，包括其功能、用途和重要性。
2. 路由和請求：詳細描述 API 的各個路由以及可用的HTTP請求方法（如GET、POST、PUT、DELETE等）。這部分通常會包括路由的 URL 和所需的請求參數。
3. 參數：對請求參數的描述，包括每個參數的名稱、類型、是否必填以及範例。
4. 回應：對 API 回應的描述，包括成功回應的格式和可能的錯誤回應。這通常包括 HTTP 狀態碼和相關的錯誤消息。
5. 身份驗證和授權：如果API需要身份驗證或授權，則文件通常會提供相關信息，例如需要 API 金鑰、token 或 OAuth 流程。
6. 版本控制：如果 API 具有多個版本，則文件通常會指示如何指定所需的 API 版本。

※ API 溝通文件的範例，「登入功能」：

這條規格講定了後端的輸出格式，以及前端必須傳入的參數。在講定文件之後，後端去開發 API 伺服器，按規格回傳資料，而前端則可以根據文件裡定義的 JSON 格式，自行模擬資料來開發畫面。

※ API 溝通文件常見格式：JSON

• JSON： JavaScript Object Notation 的縮寫，它參考了 JavaScript 中物件結構的表示方式。
• JSON的優點較為輕量、易於閱讀，幾乎所有網頁開發相關的語言都有解析 JSON 資料的函式庫。
• JSON 的語法建立在 JavaScript 對於 Array 和 Object 的表示方式，資料結構中通常也會運用 array 和 object 的嵌套關係，例如：

1. 外層是 array，裡頭包含其他 object
2. 外層是 object，裡頭還有其他 object

• JSON 還可以處理字串 (String)、數字、布林值 (Booleans) 以及空值 (null)。

※ 什麼是「後端負責回傳資料」？

前後分離的分工模式，主要差異在於，回傳 JSON v.s. 回傳 view template。後端的主要工作就是處理請求並回傳資料，而這些資料通常是以 JSON 格式回傳的。這種方式讓前端可以專注於處理使用者介面和使用者體驗，而後端則專注於資料處理和商業邏輯。這種分工模式提高了開發效率並使應用程式更易於維護。

※ 設計 Web API 

API 的設計中一般來說可以分為兩種切入點：使用者角度，以及需求角度。兩種角度在業界都很常被使用、有各自的優劣勢。

• 從需求角度看 API：等同於從單一頁面來思考，比較像 MVC 開發所做的事情。

以下圖為例，當我們想取得某個頁面，會透過一支 API 直接取得所有頁面資料；同理，在另一個頁面，也有一支 API 取得所有資料。

這種設計方式隱含的意義，就是將資料組裝的任務交給後端工程師。前端工程師會開出頁面的資料需求，後端依照需求回傳資料，填充畫面上需要的資料。

• 從使用角度看 API：後端工程師會將現有的資料開成 API 選項，前端需要使用時就自己拼湊。

這種設計方式隱含的意義，是將組裝資料的責任放到前端身上。一開始後端工程師會從資料庫確定現有的資料，再針對資料作出增刪改查的 API，前端再拿這些 API 拼湊出頁面。

以下圖為例：

1. 一個元件取一支 API，如元件 1 對應一支 API。
2. 也可能一個元件取多支 API，像元件 2 需要拿兩支 API 資料。
3. 有些元件會重複出現，像元件 2 在頁面 1、頁面 2、頁面 3 皆有出現，即會重複使用 API 3 與 API 4。

※ RESTful 風格

先提供 API 再組裝，API 設計就會跟 RESTful 風格很有關。API 的設計中命名是很關鍵的事。好的命名會讓你的 API 更易於上手與使用，而 RESTful 風格的好處就在具備非常高的可讀性，例如，我們看到 get 就知道這支 API 要拿資料，不需要看文件。