RESTful API 是什麼？RESTful API 是依照 REST（Representational State Transfer）架構原則設計的 API：系統裡的資料被看成一個個有網址的「資源」，用戶端透過 GET、POST、PUT、PATCH、DELETE 等 HTTP 方法讀取或修改它們，而且每個請求都帶齊伺服器理解它所需的資訊。MDN 也說明，以 HTTP 提供的 API 有時會被通稱為 RESTful API，即使不一定符合全部限制。外包系統時常聽到這個詞，是因為網站、App 與第三方系統都能用通用的 HTTP 工具照同一份規格溝通；驗收時要看的，是端點、參數、錯誤碼、驗證方式與版本規則有沒有寫清楚。
REST 的核心概念：資源、網址與無狀態
REST API 是什麼，要從 REST 本身談起。MDN 的定義是：REST 是一組軟體架構的設計限制，目的是讓分散式系統有效率、可靠且容易擴充。這些限制出自 Roy Fielding 的博士論文，可以整理成五點加一個選用項：
- 用戶端與伺服器分離：畫面與資料處理各自負責，可以分開開發。
- 無狀態：每個請求都要包含理解它所需的全部資訊，伺服器不靠前一次請求記住你是誰。
- 可快取：回應要標示能不能被快取，減少重複請求。
- 統一介面：用一致的方式識別與操作資源。
- 分層系統：中間可以有代理或閘道，各層只看得到相鄰的一層。
- 隨選程式碼：伺服器可傳送程式碼擴充用戶端功能，論文中屬於選用限制。
論文也說明，任何可以被命名的資訊都可以是資源。以訂單系統為例，「訂單」是一組資源，網址可能是 /orders，單筆訂單再加上訂單編號；要做什麼事，則由 HTTP 方法表達。
HTTP 方法：讀取、建立、更新與刪除
| 方法 | MDN 的說明 | 常見用途 | 重送是否冪等 |
|---|---|---|---|
| GET | 取得指定資源的表示 | 查詢訂單、會員資料 | 是 |
| POST | 送出實體，常造成伺服器狀態改變 | 建立新訂單 | 不一定 |
| PUT | 以請求內容取代目標資源的全部表示 | 整筆更新 | 是 |
| PATCH | 對資源做部分修改 | 只改收件地址 | 不一定 |
| DELETE | 刪除指定資源 | 取消或刪除資料 | 是 |
「冪等」指同樣的請求送一次或送多次，對伺服器的預期效果相同；回應可以不同，例如 DELETE 初次可能回 200，之後再送可能回 404。這和實務很有關係：網路逾時重送 GET、PUT 比較單純，重送 POST 則可能建立兩筆訂單，規格裡要寫明怎麼避免重複，例如由用戶端帶入不重複的交易編號。
狀態碼怎麼看：成功、用戶端錯誤與伺服器錯誤
MDN 把回應狀態碼分成資訊、成功、重新導向、用戶端錯誤與伺服器錯誤五類。串接時常見的如下：
| 狀態碼 | 意思 | 串接時怎麼處理 |
|---|---|---|
| 200 | 請求成功，意義依方法而定 | 讀取回應內容 |
| 201 | 成功並建立了新資源，常見於 POST | 記下新資源的編號 |
| 204 | 成功但沒有回應內容 | 不要等待回應本文 |
| 400 | 伺服器認為是用戶端錯誤，例如請求格式錯誤 | 檢查欄位與格式，修正後再送 |
| 401 | 需要先通過身分驗證 | 檢查金鑰或權杖是否正確、過期 |
| 403 | 伺服器理解請求但拒絕處理，重新驗證也沒有差別 | 確認帳號權限，不要原樣重送 |
| 404 | 找不到資源；在 API 中也可能是端點正確但該筆資料不存在 | 確認路徑與資料編號 |
| 500 | 伺服器遇到無法處理的狀況 | 記錄後通知對方，稍後再試 |
MDN 也提醒，伺服器可能用 404 代替 403，以免讓未授權的用戶端知道資源存在。所以判斷錯誤時，要對照對方文件，不要只看狀態碼的名稱。
JSON：請求與回應的資料格式
REST 本身沒有規定資料格式，JSON 是可用的格式之一。MDN 說明 JSON 是一種資料交換格式，可以表示數字、布林值、字串、null、陣列與物件，許多程式語言都支援。規格書裡關於資料格式，至少要寫清楚：
- 欄位名稱與型別，哪些必填、哪些可省略。
- 日期時間的格式與時區，金額的單位與小數位數。
- 沒有值時是回傳 null、空字串，還是不出現這個欄位。
- 清單資料怎麼分頁，一次回傳幾筆、怎麼取得下一頁。
這些細節沒寫清楚，系統串起來後就可能出現資料對不上的情況。
REST 和其他 API 風格差在哪
| 風格 | 溝通方式 | 適合情境 |
|---|---|---|
| REST | 每種資源有自己的網址，用 HTTP 方法操作 | 網站、App 與後台之間的一般資料存取 |
| GraphQL | 單一端點，通常是 /graphql，用戶端在查詢中指定要哪些欄位 | 畫面需要的資料組合多變，想只取需要的欄位 |
| SOAP | 以 XML 定義訊息框架的協定，可透過多種底層協定傳送 | 對方系統只提供 SOAP 介面時 |
| Webhook | 事件發生時由對方主動通知你的伺服器 | 付款完成、訂單狀態改變等即時通知 |
Webhook 和 REST 可以搭配使用：對方用 Webhook 通知「有新事件」，你的系統再用 REST API 查詢完整資料。API 的基本觀念可參考API是什麼與企業系統的用途。
外包系統時為什麼常提到 RESTful API
MDN 說明，入門時可以把 REST API 理解成能用標準網頁函式庫與工具呼叫的 HTTP 服務。這讓它在外包專案中有幾個好處：
- 前後端可以分開開發：網站、App 與後台共用同一組 API，各自由不同團隊負責。
- 日後串接其他系統較容易：金流、物流或客戶管理系統若也提供 HTTP API，串接方式相近。
- 規格可以寫成機器可讀的文件：OpenAPI 規格是與程式語言無關的 HTTP API 描述標準，可用 JSON 或 YAML 撰寫，並供文件產生、程式碼產生與測試工具使用。
和外部系統串接時的盤點與時程，可參考API串接的流程與規格確認。
驗收時要看的 API 規格清單
- 端點與方法：每個網址支援哪些方法，對應的業務動作是什麼。
- 參數與欄位：必填與選填、型別、長度限制與範例。
- 錯誤處理：每個端點可能回傳的狀態碼，以及錯誤訊息的格式。
- 驗證與權限：用金鑰還是權杖、怎麼取得與更新、不同角色能存取哪些資源，可參考API Key 和 Token 的差別。
- 版本規則：版本怎麼標示，改版時舊版保留多久、怎麼通知。
- 文件與測試環境：是否交付 OpenAPI 等格式的文件與測試帳號，原始碼與文件的權利歸屬寫進合約。
常見問題
RESTful API 和 REST API 一樣嗎？
口語上常混用。嚴格來說，RESTful 指符合 REST 限制的設計，但 MDN 也說明，以 HTTP 提供的 API 有時會被通稱為 RESTful，即使不完全符合；驗收時以實際規格為準。
RESTful API 一定要用 JSON 嗎？
不一定。REST 是架構原則，沒有規定資料格式，也可以使用 XML 等格式。用哪一種、編碼與欄位規則如何，要在雙方的規格書中寫清楚。
PUT 和 PATCH 差在哪？
PUT 是用請求內容取代整筆資源，沒送的欄位可能被清空；PATCH 只修改送出的部分。PUT 是冪等的，PATCH 則不一定，重送前要確認對方的處理方式。
收到 401 和 403 要怎麼判斷？
401 表示需要先通過身分驗證，通常要檢查金鑰或權杖；403 表示伺服器拒絕處理，重新驗證也不會改變，要確認帳號是否有這項權限。
沒有 API 文件的系統可以串接嗎？
風險很高。欄位意義、錯誤處理與權限都只能猜測，對方改版時也可能沒有通知。建議先請廠商補文件與測試環境，或改用檔案匯出等其他交換方式。
本文由京采數位科技整理。我們自 2005 年起提供官網設計、系統開發與 Google SEO 服務，實際案例可見成果與案例。
想直接討論你自己的網站狀況，或需要一份初步的搜尋機會評估？
相關主題
下一步
外包系統前，建議先列出要和哪些系統交換資料、哪些畫面需要 API，並要求廠商交付可測試的 API 文件。京采的網頁設計服務可以協助需求釐清、撰寫與審閱 API 規格，並開發官網、後台與既有系統之間的 API 串接，歡迎與我們聯繫討論。
