在這系列的前幾篇文章著重在個體,探討了網頁端是怎麼由 HTML 組成以及透過 CSS 長成什麼樣子,這篇文章會來介紹前後端溝通的重要觀念 API。
什麼是 API
API (Application Programming Interface),中文是應用程式介面,介面是用於程式間溝通的抽象概念。
溝通,重要的是訊息的交換
以男女交往來說重要的溝通是
- 丟球: 會不會丟球,不會丟球對方就不知道該怎麼和你進一步互動
- 接球: 對方丟球該怎麼接到,該怎麼看到球飛過來
人與人之間的情感,就是透過傳接球這個介面來慢慢讓感情升溫的,搞不清楚介面,會憑實力單身。
API 介面在前後端之間扮演的角色就是提供請求和回覆的格式和規範,在設計 API 的時候,對 API 而言重要的是
- 傳入: 收到什麼樣子的參數
- 傳出: 回傳什麼樣子的結果
當我們完整的定義了 “傳入“ 和 “傳出“ 參數的樣子後,也就完成了 API 的設計。
前後端之間溝通重要的傳入和傳出是
- Request: 前端向後端請求資料
- Response: 後端回覆前端的請求
什麼是 Request
Request 是瀏覽器向後端取得資料的方式,一個 Request 通常包含以下參數
- URL: 要跟後端的哪個路徑互動
- method: HTTP method
- headers: Client Request 的相關資訊
- body: 資料類型且需要傳輸的內容大多會存放在此
- credntial: 像是同源政策類的設定
什麼是 Response
Response 則是定義了瀏覽器可以取得的資料格式,一個 Response 通常包含以下參數
- headers: Server Response 的相關資訊
- body: 資料類型且需要傳輸的內容大多會存放在此
- status: 回應請求的狀態
- statusText: 狀態相關的訊息
什麼是 RESTful API
REST (Representational State Transfer) 是一種依照資源來設計 API 界面的一種架構,透過架構來定義 API 的傳入和傳出該如何去組成和設計,通常 RESTful API 會是在講基於 HTTP 通訊協定上的介面服務設計。
資源指的是任何可以讓用戶端存取的物件、資料、服務
資源必須具有識別碼 (ID) 也就是 URI 來讓用戶進行存取,接著會透過 REST 這種交換資源的表示法來與資源互動。
舉女孩子喜歡吃的美食當例子
- 傳入:
/users/ariel/favorite-food-list/
- 傳出: 甜點店清單、火鍋店清單、早午餐店清單
RESTful API 會使用標準的 HTTP method 當作動詞來對資源進行操作
- GET: 取得資料
- POST: 新增資料
- PUT: 修改資料
- DELETE: 刪除資料
依照 RESTful API 來設計 API 的 URI 應該避免把動詞放在 URI 中 /create-favorite-food-list/
較好的方式會是 /favorite-food-list/
+ POST。
一般來說 URI 中的資源都會是複數名詞,並且透過階層來描述資源之間的關係:
/users/ariel
: 代表取得 ariel 這個使用者的相關資訊/users/ariel/favorite-food-list/
: 代表 ariel 的美食清單
不過一般建議階層最多就是兩層即可,避免造成設計上的複雜以及使用彈性的下降。
在對資源操作過後,在傳出時也有幾個常用的狀態碼
- 200: 成功
- 201: 已建立
- 204: 沒有內容
- 400: 無效的請求
- 404: 找不到
- 409: 衝突,通常會用在 PUT 失敗
OpenAPI Specification
OpenAPI Specification 是一種機器可讀介面文件的規範,用來描述、生成、使用和視覺化 RESTful Web 服務。
常聽到的產品會是 Swagger,以前 OpenAPI 是 Swagger 框架的一部分,在 2016 年後成為一個獨立項目,受到 Linux 基金會的一個開源協作項目 OpenAPI Initiative 監督。
Swagger
Swagger 是 REST API 的工具,可以自動建立清晰明瞭的 REST API 文件,在開發流程上幫助設計、構建、記錄和使用 REST API。
推薦大家可以直接使用線上的編輯器去體驗,傳送門在此:
原則上就是透過編輯 yaml 檔來定義 API 的傳入和傳出,貼上最基本範例,定義了 book 相關的 API 和參數內容。
swagger: "2.0"
info:
description: "API 文件"
version: "1.0.0"
title: "Swagger Book Store"
host: "swagger.io"
basePath: "/v1"
schemes:
- "https"
- "http"
paths:
/api/v1/book/{bookId}:
get:
tags:
- "Book"
summary: "Find Book by ID"
description: "For valid response try integer IDs with value >= 1"
operationId: "getBookById"
produces:
- "application/json"
parameters:
- name: "bookId"
in: "path"
description: "ID of pet that needs to be fetched"
required: true
type: "integer"
maximum: 10.0
minimum: 1.0
format: "int64"
responses:
"200":
description: "successful operation"
schema:
$ref: "#/definitions/Book"
"400":
description: "Invalid ID supplied"
"404":
description: "Order not found"
definitions:
Book:
type: "object"
properties:
id:
type: "integer"
format: "int64"
JS Doc
如果不使用 REST 的規範又想要額外撰寫相關的傳入和傳出,Node 的後端通常會需要透過 JSDoc 註解產生 API 文件。
/**
* Represents a book.
* @constructor
* @param {string} title - The title of the book.
* @param {string} author - The author of the book.
*/
function Book(title, author) {}
只要下指令安裝 npm install jsdoc
,然後就可以直接 jsdoc yourJavaScriptFile.js
在短短幾秒內自動生成出網頁版的 API 文件。
不過檔案內容當然要搭配上特殊的註解 /**
開頭,這樣才可以被 JSDoc 辨識出來。
喜歡這篇文章,請幫忙拍拍手喔 🤣