新手指南：什麼是 RESTful API？

如果你正在學習網頁開發，一定會常常聽到「API」這個詞。

前端工程師說要「串 API」，後端工程師說要「開 API」，到底 API 是什麼？

而 RESTful API 又是什麼？

這篇文章會用最白話的方式，帶你搞懂這些概念。

先搞懂 API 是什麼

在講 RESTful API 之前，我們要先知道什麼是 API。

在網頁和 App 的世界裡，通常會分成「前端」和「後端」兩個部分。

前端就是你看到的畫面。

當你打開一個網站，看到的文字、圖片、按鈕、輸入框，這些都是前端負責呈現的。

手機 App 也是一樣，你滑的那個介面就是前端。

後端則是你看不到的部分，它是一台伺服器，負責存放和處理資料。

比如說，你的會員帳號、購物車內容、聊天紀錄，這些資料都存在後端伺服器裡。

前端本身不存資料，它只負責「顯示」。

所以當前端需要資料的時候，就必須跟後端要。

而 API 就是前端跟後端之間溝通的管道。

flowchart LR
    A[前端
使用者看到的畫面] <-->|API| B[後端
存放資料的伺服器]

舉個實際的例子：

當你打開天氣 App 想看今天的天氣，App 畫面本身並沒有存放天氣資料。

App 會透過 API 發送一個「請求」給氣象局的伺服器，告訴它：「我要台北現在的天氣資料。」

伺服器收到請求後，就會把天氣資料「回傳」給 App。

App 拿到資料後，再把它顯示在畫面上。

這整個「發送請求 → 取得回應」的過程，就是透過 API 完成的。

sequenceDiagram
    participant A as 天氣 App
    participant B as 氣象局伺服器
    A->>B: 發送請求：我要台北的天氣資料
    B->>A: 回傳資料：台北，晴天，25°C
    Note over A: 把天氣資料顯示在畫面上

REST 是一種設計風格

前面提到，前端會透過 API 跟後端要資料。

但「怎麼要」其實有很多種做法，前端跟後端溝通時會碰到一些問題。

怎麼告訴後端「我要的是哪一種資料」？

假設後端有使用者資料、商品資料、訂單資料。

前端要怎麼說清楚自己要的是哪一個？

怎麼告訴後端「我想做什麼操作」？

同樣是使用者資料，我是想「查詢」、「新增」、「修改」還是「刪除」？

前端要怎麼讓後端知道？

如果沒有統一的規則，每個工程師都用自己的方式來設計，會發生什麼事？

前端要跟後端要資料時，會呼叫後端提供的 API。

每個 API 都有一個名稱，讓前端知道要呼叫哪一個。

但如果沒有統一規則，每個後端工程師取名的方式都不一樣。

假設三個工程師都要設計一個「取得使用者資料」的 API：

• A 工程師把 API 取名叫 getUsers
• B 工程師把 API 取名叫 fetchAllUsers
• C 工程師把 API 取名叫 user_list

三個人做的事情一樣，但命名方式完全不同。

前端工程師每次串接不同的 API，都要重新搞懂對方的命名習慣，效率很差。

所以就需要有一套統一的規則，讓大家都用一樣的方式來設計 API。

目前常見的 API 設計規則有好幾種，比如 REST、GraphQL、gRPC 等等。

每種規則都有自己的特色和適用情境，但你不需要現在全部搞懂。

這篇文章要介紹的 REST，是目前最多人使用、也最容易入門的一種。

REST 用網址區分資料

REST 規定：用「網址」來區分你要的是哪一種資料。

還記得前面提到的問題嗎？後端有使用者資料、商品資料、訂單資料，前端要怎麼說清楚自己要的是哪一個？

REST 的做法是：每一種資料都給它一個專屬的網址。

比如說：

• https://example.com/users 這個網址，代表使用者資料
• https://example.com/products 這個網址，代表商品資料
• https://example.com/orders 這個網址，代表訂單資料

前端想要使用者資料，就對 https://example.com/users 發送請求。

前端想要商品資料，就對 https://example.com/products 發送請求。

網址不同，拿到的資料就不同。

這樣一來，光看網址就知道前端要的是什麼，非常清楚。

在 REST 的術語裡，這些資料叫做「資源」。

所以你會聽到有人說：每一個網址都代表一個資源。

意思就是：每一種資料都有自己專屬的網址。

REST 用 HTTP 動詞區分操作

前端跟後端溝通時，雙方要用同一種「語言」才能互相理解。

這個語言就是 HTTP。

當你在瀏覽器輸入網址、點擊連結、或是送出表單時，瀏覽器都是用 HTTP 在跟伺服器溝通。

在 HTTP 裡面，有一些「動詞」可以用來表示你想做什麼事。

這些動詞就叫做「HTTP 動詞」或「HTTP 方法」。

REST 規定：用不同的「HTTP 動詞」來區分你想做什麼操作。

前端發送請求時，會帶上一個 HTTP 動詞，告訴伺服器「我想對這個資料做什麼」。

常用的 HTTP 動詞有四個：

這四個動詞對應到資料庫的四種基本操作：新增、讀取、更新、刪除（也就是常說的 CRUD）。

實際範例：會員管理系統

前面分開介紹了「用網址區分資料」和「用 HTTP 動詞區分操作」。

現在把這兩個概念組合起來，看看實際的 API 會長什麼樣子。

假設你在做一個會員管理系統，裡面有很多使用者的資料。

用 REST 的規則來設計，你的 API 會這樣規劃：

決定資源的網址

首先，要給「使用者資料」一個專屬的網址。

我們把它設為 https://example.com/users。

所有跟使用者有關的操作，都會透過這個網址來處理。

搭配 HTTP 動詞來區分操作

網址決定了「要操作什麼資料」，接下來要決定「要做什麼操作」。

這時候就要搭配不同的 HTTP 動詞。

想要「查詢」所有使用者的資料：

用 GET 動詞，對 https://example.com/users 發送請求。

想要「查詢」某一個使用者的資料：

用 GET 動詞，對 https://example.com/users/1 發送請求。

網址最後面的 1 是使用者的 ID，代表「我要查的是 ID 為 1 的那個使用者」。

想要「新增」一個使用者：

用 POST 動詞，對 https://example.com/users 發送請求。

想要「修改」某個使用者的資料：

用 PUT 動詞，對 https://example.com/users/1 發送請求。

想要「刪除」某個使用者：

用 DELETE 動詞，對 https://example.com/users/1 發送請求。

REST API 網址與 HTTP 動詞對照表

你會發現，網址幾乎都是 https://example.com/users，差別只在於搭配的 HTTP 動詞不同。

這就是 REST 的設計邏輯：

• 網址決定「你要操作什麼資料」
• HTTP 動詞決定「你要對這個資料做什麼操作」

什麼是 RESTful API？

前面介紹了 REST 的兩個核心規則：用網址區分資料、用 HTTP 動詞區分操作。

遵循這些 REST 規則設計出來的 API，就叫做 RESTful API。

RESTful API 有四個主要特點：

以資源為中心

這個前面已經說明過了。

每一種資料都有自己專屬的網址。

看到 https://example.com/users 就知道是使用者資料。

看到 https://example.com/products 就知道是商品資料。

網址的命名要清楚，讓人一眼就知道這是什麼資料。

使用標準的 HTTP 動詞

這個前面也說明過了。

用 GET 表示查詢、POST 表示新增、PUT 表示修改、DELETE 表示刪除。

大家都用一樣的規則，不需要自己發明新的操作名稱，溝通起來更方便。

無狀態（Stateless）

這個概念是什麼意思？

假設你發送了兩次請求給伺服器：

• 第一次請求：查詢 ID 為 1 的使用者
• 第二次請求：修改這個使用者的名字

在「無狀態」的設計下，伺服器不會記得你第一次查了誰。

所以第二次請求時，你不能只說「把剛剛那個使用者的名字改掉」。

你必須再次告訴伺服器「我要修改的是 ID 為 1 的使用者」。

每一次請求都是獨立的，伺服器只看這一次請求的內容，不會參考之前的紀錄。

這樣設計的好處是：伺服器不需要記住每個使用者的狀態，處理起來更單純，也更容易擴充。

用 JSON 格式傳輸資料

前端發送請求後，伺服器會回傳資料。

這些資料要用什麼格式傳輸呢？

目前最常見的格式是 JSON。

JSON 長這樣：

{
  "id": 1,
  "name": "小明",
  "email": "ming@example.com"
}

{
  "id": 1,
  "name": "小明",
  "email": "ming@example.com"
}

JSON 的結構很簡單，就是一組一組的「名稱：值」。

上面這個例子裡：

• "id": 1 表示這個使用者的 ID 是 1
• "name": "小明" 表示這個使用者的名字是小明
• "email": "ming@example.com" 表示這個使用者的 Email 是 ming@example.com

JSON 的好處是結構清楚、容易閱讀，而且幾乎所有的程式語言都能處理它。

所以 JSON 成為 API 資料傳輸的主流格式。

RESTful API 用在哪裡？

RESTful API 的應用非常廣泛，幾乎所有的網站和 App 都會用到。

社群平台

Facebook、Instagram、Twitter 這些平台都有提供 RESTful API。

開發者可以透過這些 API 來讀取貼文、發布內容、或是取得使用者資料。

電商網站

當你在購物網站瀏覽商品、加入購物車、送出訂單時，這些操作背後都是透過 API 跟伺服器溝通。

天氣 App

天氣 App 會串接氣象服務的 API，取得即時的天氣資料後顯示在畫面上。

小結

讓我們複習一下今天學到的重點：

1. API 是讓兩個程式互相溝通的方法，在網頁開發中通常是前端和後端之間的溝通管道
2. REST 是一種設計 API 的規則，核心概念是「每個網址代表一個資源」
3. HTTP 動詞用來表示要對資源做什麼操作：GET 讀取、POST 新增、PUT 更新、DELETE 刪除
4. RESTful API 就是遵循 REST 規則設計的 API，有四個特點：以資源為中心、無狀態、使用標準 HTTP 動詞、用 JSON 傳輸資料

理解 RESTful API 是前後端開發的基礎知識。

不管你未來想做前端、後端、或是全端，都會需要用到這些概念。