RESTful API 是什麼?該怎麼理解?: 從把妹角度理解前後端如何和平相處 | 前端三分鐘

文章目錄

1. 什麼是 API
1. 1.1. 什麼是 Request
2. 1.2. 什麼是 Response
2. 什麼是 RESTful API
3. OpenAPI Specification
1. 3.1. Swagger
4. JS Doc

在這系列的前幾篇文章著重在個體，探討了網頁端是怎麼由 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。

推薦大家可以直接使用線上的編輯器去體驗，傳送門在此:

https://editor.swagger.io/

原則上就是透過編輯 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 辨識出來。

更多相關文章

喜歡這篇文章，請幫忙拍拍手喔 🤣

RESTful API 是什麼?該怎麼理解? 從把妹角度理解前後端如何和平相處