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