RESTful API 概念與開發規範 定義 HTTP 方法與 OpenAPI 實踐以優化協作效率

什麼是 RESTful API？

RESTful API 是一種基於 REST (Representational State Transfer) 架構風格的網路應用程式介面設計標準。它利用 HTTP 通訊協定的原生特性，將網路上的所有事物視為「資源」(Resource)，並透過標準的 HTTP 方法（如 GET 用於取得、POST 用於新增、PUT 用於更新、DELETE 用於刪除）來對這些資源進行操作。這種設計模式強調無狀態性 (Statelessness) 與統一介面，使前後端系統能解耦開發、易於擴展且具備良好的可讀性，是現代 Web 服務溝通的主流標準。

在这系列的前幾篇文章著重在個體，探討了網頁端是怎麼由 HTML 組成以及透過 CSS 長成什麼樣子。這篇文章會來介紹前後端溝通的重要觀念 RESTful API。

什麼是 API：程式間的溝通介面

API (Application Programming Interface)，中文是應用程式介面，介面是用於程式間溝通的抽象概念。

溝通，重要的是訊息的交換

以男女交往來說重要的溝通是：

• 丟球：會不會丟球，不會丟球對方就不知道該怎麼和你進一步互動。
• 接球：對方丟球該怎麼接到，該怎麼看到球飛過來。

人與人之間的情感，就是透過傳接球這個介面來慢慢讓感情升溫的，搞不清楚介面，會憑實力單身。

API 介面 在前後端之間扮演的角色就是提供請求和回覆的格式和規範。在設計 API 的時候，對 API 而言重要的是：

• 傳入：收到什麼樣子的參數。
• 傳出：回傳什麼樣子的結果。

當我們完整的定義了「傳入」和「傳出」參數的樣子後，也就完成了 API 設計。

前後端之間溝通重要的「傳入」和「傳出」是：

• Request：前端向後端請求資料。
• Response：後端回覆前端的請求。

什麼是 Request：前端發送請求的核心構成

Request 是瀏覽器向後端取得資料的方式。一個 Request 通常包含以下參數：

• URL：要跟後端的哪個路徑互動。
• method：HTTP 方法，如 GET、POST 等。
• headers：Client Request 的相關資訊。
• body：資料類型且需要傳輸的內容大多會存放在此。
• credential：像是同源政策類的設定。

什麼是 Response：後端回傳資料的標準格式

Response 則是定義了瀏覽器可以取得的資料格式。一個 Response 通常包含以下參數：

• headers：Server Response 的相關資訊。
• body：資料類型且需要傳輸的內容大多會存放在此。
• status：回應請求的狀態（HTTP 狀態碼）。
• statusText：狀態相關的訊息。

RESTful API 核心概念：資源導向的設計原則

REST (Representational State Transfer) 是一種依照資源來設計 API 介面 的一種架構，透過架構來定義 API 的「傳入」和「傳出」該如何去組成和設計。通常 RESTful API 會是在講基於 HTTP 通訊協定上的介面服務設計。

資源指的是任何可以讓用戶端存取的物件、資料、服務。

資源必須具有識別碼 (ID)，也就是 URI，來讓用戶進行存取。接著會透過 REST 這種交換資源的表示法來與資源互動。

舉女孩子喜歡吃的美食當例子：

• 傳入：/users/ariel/favorite-food-list/
• 傳出：甜點店清單、火鍋店清單、早午餐店清單

RESTful API 會使用標準的 HTTP 方法 當作動詞來對資源進行操作：

• 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 的美食清單。

不過一般建議階層最多就是兩層即可，避免造成設計上的複雜以及使用彈性的下降。

在對資源操作過後，在「傳出」時也有幾個常用的 HTTP 狀態碼：

• 200：成功。
• 201：已建立。
• 204：沒有內容。
• 400：無效的請求。
• 404：找不到。
• 409：衝突，通常會用在 PUT 失敗。

OpenAPI Specification：機器可讀的 API 文件標準

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 和參數內容。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

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 文件。

1
2
3
4
5
6
7

/**
 * 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 辨識出來。

FAQ：RESTful API 常見問題

Q1：為什麼大家都推薦 RESTful API？

A：因為它基於 HTTP 協議，具有無狀態 (Stateless) 特性，這讓伺服器不需要記住用戶的 session 狀態，容易進行橫向擴展 (Scale-out)。此外，它的 URI 設計直觀（資源導向），讓開發者能快速理解 API 的用途。

Q2：PUT 與 PATCH 有什麼不同？

A：PUT 是「整份替換」，即更新資源時需要提供完整的資料內容；PATCH 則是「部分更新」，只傳送需要修改的欄位即可。實務上，為了減少頻寬消耗，PATCH 在某些場景下更受歡迎。

Q3：RESTful API 與 GraphQL 的主要區別是什麼？

A：RESTful 針對每個資源有固定的 Endpoint（如 /users/1），容易產生「過度獲取 (Over-fetching)」或「獲取不足 (Under-fetching)」的問題；GraphQL 則只有一個 Endpoint，允許客戶端精確指定需要的欄位，解決了上述問題，但學習曲線與實作複雜度較高。

• ← 上一篇
• 下一篇 →