RESTful API 驗收怎麼做？從 HTTP 方法、冪等性到跨帳號權限的 8 項檢查

一家企業的官網、CRM 與 ERP 都有 API，業務仍得每天匯出 Excel，對照訂單、客戶與庫存。問題未必是「沒有串接」，更可能是系統之間沒有說清楚：誰能查什麼、資料如何表示、失敗時能否重送、更新後應收到什麼回應。

RESTful API 可以提供一致的系統溝通方式，但它不是一個買來就能解決整合問題的工具。真正重要的是：讓每一次請求都能辨識資源、理解操作、確認結果，並在權限與錯誤情境下維持可預期的行為。企業要驗收的不是「API 有沒有通」，而是「整個業務流程能不能安全、重複、正確地完成」。[S01][S02]

先看一張訂單：API、REST 與 RESTful 到底差在哪裡？

想像客戶在購物網站下單。前台要顯示訂單狀態，客服要查配送進度，ERP 要更新庫存，財務要核對付款。各系統都需要知道同一張訂單發生什麼事，卻不應直接碰觸彼此的資料庫。

API（Application Programming Interface）是軟體對其他軟體開放的能力與規則。它回答的是「我能向這套系統提出什麼請求、拿到什麼結果」。REST（Representational State Transfer）則是 Roy Fielding 所提出的一種網路軟體架構風格，強調以資源為核心，讓元件透過具一致語意的介面互動。[S01]

按照 REST 思想設計的 API，常被稱為 REST API 或 RESTful API。日常業界語境裡，RESTful 常用來形容以 HTTP、資源路徑與 JSON 建立的 Web API。不過，使用 JSON 不等於 REST；把網址命名成 /orders 也不代表已完整符合 REST 架構約束。嚴格而言，REST 還包含用戶端與伺服器分離、無狀態、快取、分層系統、統一介面，以及超媒體作為應用狀態引擎等設計要求，另有選擇性的隨需程式碼限制。[S01][S09]

因此，當供應商說「我們提供 RESTful API」，最有用的下一句不是「你用哪種語言開發」，而是「能否提供端點、資料欄位、權限、錯誤與重試規則，讓我們實際驗收」。這份規格能否被前後端共同理解，比名詞是否流行更重要。

一次完整的 REST API 呼叫，究竟發生了什麼？

以查詢一筆訂單為例，前台發出以下請求：

GET /api/orders/O1001 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer <access-token>

伺服器會解讀 HTTP 方法與資源位置，依身分與權限檢查請求，從後端系統取得資料，再回傳 HTTP 狀態碼與資料內容。假設查詢成功，可能收到：

HTTP/1.1 200 OK
Content-Type: application/json

{
  "orderId": "O1001",
  "status": "SHIPPED",
  "totalAmount": 1200,
  "currency": "TWD"
}

這是一個教學示例，不是某家企業的真實 API，也不是可直接在公開網站呼叫的服務。

把流程拆開看，網址 /api/orders/O1001 指出要處理哪一筆資源；GET 表示希望取得該資源的表示；Authorization 傳送驗證憑據；200 OK 表示這次請求成功；JSON 則是回應內容的一種常見格式。真正的 API 還需要定義欄位型別、金額幣別、時區、錯誤結構及誰有權讀取這筆訂單。[S02][S03][S04]

企業常見的誤會，是認為資料庫裡有一個 orders 資料表，API 就一定要和資料表一對一。事實上，API 資源是對外承諾的業務概念，不是直接暴露內部資料庫結構。伺服器可以從 ERP、物流系統與付款服務整合出一份訂單表示；只要介面契約穩定，內部技術仍可調整。[S01]

GET、POST、PUT、PATCH、DELETE：動詞用錯，整合就容易出事

常見 HTTP 方法並不是自由命名的按鈕，而是有明確語意的操作。以訂單系統為例：[S03]

其中值得資訊主管特別認識的是「冪等性」（Idempotency）。白話說，相同操作執行一次，和重複執行多次，對伺服器產生的預期效果相同。GET、PUT、DELETE 在 HTTP 規範中具有冪等語意，但 POST 與 PATCH 不保證如此；這不代表每次回應碼必定相同，也不表示錯誤的系統實作會自動安全。[S03][S05]

例如付款請求已送出，但網路中途斷線，使用者以為沒付款又按一次。若付款服務採 POST，且沒有重送保護，可能產生重複處理風險。實務上常針對建立訂單或收款等寫入操作，設計具有效期與儲存規則的 Idempotency Key、唯一業務識別碼或交易去重機制。但冪等鍵不是 HTTP 自動提供的魔法，必須由服務端明確實作與驗收。

另一個關鍵是 GET 不應拿來「確認收款」或「刪除資料」。HTTP 將 GET 定義為安全方法，意即用戶端不藉此要求改變業務狀態。伺服器仍可記錄存取日誌，但不能把具有商業副作用的動作偽裝成單純查詢；否則預載、快取或爬蟲都可能造成不可預期後果。[S03]

同樣回傳 JSON，為何前後端還是對不起來？

因為「資料能被讀取」和「資料有一致意義」是兩件不同的事。假設 ERP 回傳 totalAmount: 1200，CRM 認為它是未稅金額，前台則顯示成含稅售價。三個系統都能成功解析 JSON，客戶看到的數字仍然可能錯誤。

企業應該要求一份最基本的 API 契約，明確寫出路徑、方法、必要參數、資料型別、是否允許 null、金額單位、時間格式、授權條件、成功與失敗回應。OpenAPI 是描述 HTTP API 的公開規格之一，可以用機器可讀的方式定義路徑、操作與輸入輸出，協助建立文件、測試與協作流程。[S07]

但文件並不是實作的保證。即使 OpenAPI 定義得很完整，實際系統也可能傳出錯誤客戶的訂單，或把已取消的訂單當成已出貨。這類問題要用契約測試、整合測試與業務驗收共同發現，不能只靠「Swagger 畫面可以打開」。如果要深入理解規格與驗證的分工，可延伸閱讀本站〈API 契約是什麼？從 OpenAPI、前後端協作到 AI Coding〉。

錯誤碼也是契約的一部分。常見語意包括 200 代表成功、201 代表建立新資源、204 代表成功但沒有回應內容、400 代表請求有問題、401 表示需要有效驗證、403 表示拒絕存取、404 表示找不到資源、409 表示與目前資源狀態衝突、429 表示請求過多。實際應用須依情境選用，不能把所有成功與失敗都包成 200 OK，再要求前台猜測。[S04]

無狀態不是沒有資料庫；能登入也不代表能看所有訂單

REST 的無狀態（Stateless）要求每次請求都攜帶足以讓伺服器理解與處理的必要資訊，不依賴伺服器記得「上一個請求進行到哪裡」。這不代表後端不能保存訂單、付款或庫存資料；它限制的是用戶端與伺服器之間的互動狀態依賴，不是取消企業資料庫。[S01]

技術團隊可能採用存取權杖，例如 Bearer Token 來表明呼叫身分。但拿到有效 Token，只能證明某些驗證條件通過，不代表呼叫者可以存取任何訂單。這正是企業 API 的重要風險：物件層級授權失效。

OWASP 的 API 安全指引明確指出，當 API 依使用者提供的訂單 ID 或其他物件識別碼取得資料時，每次都需要檢查呼叫者是否有權存取這一筆物件。假設 A 客戶可以查 /orders/O1001，他把網址改成 /orders/O1002，系統就回傳 B 客戶訂單；即使整個系統都採 HTTPS、有登入、有 Token，仍然存在嚴重授權問題。[S06]

因此，API 驗收至少要包含三種不同身分：合法擁有者、已登入但未授權者，以及未登入者。針對高風險寫入，還要驗證角色權限、資料欄位遮罩、操作日誌、速率限制與異常處理。OpenAPI 可以記錄權限需求，但真正的授權必須由後端執行，不是靠前端把按鈕藏起來。

當 AI Agent 也要查 ERP，RESTful API 為何更重要？

企業希望 AI Agent 不只回答文字，還能即時查訂單、比對庫存、建立客服案件。這時候，Agent 需要的不是資料庫最高權限，而是幾個邊界清楚、能記錄與驗證的操作能力。

例如，先開放唯讀的 GET /orders/{id}，由後端確認員工身分、資料範圍、欄位遮罩與查詢限制。等查詢結果、錯誤處理和稽核紀錄都通過驗收，再考慮開放「建立售後案件」這類寫入操作。即使透過 MCP 或 AI Tool Calling 提供工具，底層的 API 授權與業務規則仍然要維持；多一層 AI 介面不會自動解決存取控制。

實務上，一個工具可能呼叫 REST API，也可能透過其他協定與系統溝通；RESTful API 並不是 AI Agent 的唯一選項。它在企業整合中的價值，是讓 AI、前台、報表系統與合作夥伴能沿用相對一致、可測試、可治理的功能邊界。這是架構推論，不是保證某種 API 一定比較安全或省成本。

若以 Java 生態實作，Spring 官方教學示範使用 @RestController 定義 HTTP 請求處理，並回傳資料表示；實務上還需要補足資料存取、權限、驗證、錯誤處理與可觀測性，不能把教學範例當成可直接上線的完整系統。[S08] 相關背景可參考本站〈Spring Boot 是什麼？Java 後端架構、企業實作與 Spring AI 指南〉。

不看程式碼，企業也能驗收的 8 個問題

以下是一張可供資訊主管、專案經理與委外廠商共同使用的原創 API 驗收卡。不必先學會 Java 或 PostgreSQL，也能釐清整合是否真的可用。

把驗收卡變成可重現的測試紀錄

驗收前，先在獲授權的測試環境建立 A、B 兩個帳號與各自的測試訂單，記下初始資料；不要拿真實客戶資料或正式收款流程練習。以下是測試設計示例，並非本文已執行的系統測試。

每一項紀錄至少保存測試時間、API 版本、去識別化的請求與回應、請求識別碼、前後資料差異，以及預期／實際結果。憑據必須遮罩；若只能提供一張「呼叫成功」截圖，仍不足以判斷資料副作用與跨帳號權限是否正確。

最有價值的驗收方式，是選一條真正重要的流程，例如「客戶下單後，客服能在 1 次查詢中看到正確訂單狀態」，再安排正常查詢、錯誤訂單編號、越權查詢、網路重試與併發更新等測試。不要只驗「API 可回傳資料」，而要驗「資料是否正確、權限是否恰當、重試是否安全、異常是否可追蹤」。

這裡也需要避免另一種極端：並非所有企業都需要把每項服務改造成 RESTful API。批次匯入、事件驅動、GraphQL 或 gRPC 等方式，在不同需求下也可能更適合。RESTful API 是一種架構選擇；真正的決策標準仍是系統相容性、資料一致性、維運能力、交易風險與整體成本。

結語：介面可以串接，責任不能省略

RESTful API 讓企業有機會用相對一致的方式連接不同系統，但它不會自動修正錯誤資料、不會自動授權，也不會保證斷線重送不會重複扣款。API 是否成熟，應看跨系統協作的結果能否被驗證，而不是看端點數量或技術名稱。

下一次評估 ERP、CRM 或 AI Agent 整合，先選定一條高價值流程，要求供應商提供可執行的 API 契約、測試情境與責任界線。當資訊主管與業務主管能用同一張驗收卡討論「什麼叫成功」，整合才算真正開始。

參考資料與查核說明

本文技術依據以 REST 原始論文、HTTP 參考文件、OWASP 官方安全指引、OpenAPI 學習文件與 Spring 官方教學為主。文中訂單編號、金額、使用情境及驗收卡均屬編輯示例，不是實際企業客戶成果；HTTP 行為與系統實作可能隨需求與規範版本有所差異。

[S01] Roy T. Fielding，Architectural Styles and the Design of Network-based Software Architectures，Chapter 5

[S02] AWS，什麼是 RESTful API

[S03] MDN，HTTP request methods

[S04] MDN，HTTP response status codes

[S05] MDN，Idempotent

[S06] OWASP，API1:2023 Broken Object Level Authorization

[S07] OpenAPI Initiative，API Endpoints

[S08] Spring，Building a RESTful Web Service

[S09] Google Cloud，REST API 基礎

圖片與素材說明

本文封面為 AI 生成的原創概念插畫，呈現不同系統透過 API 互動的示意關係，非實際系統架構圖、產品介面或企業實測畫面。視覺資料庫僅用於抽象構圖語法分析，未將參考圖、第三方 Logo 或品牌元素複製到成品。

作者：天地人 TDR 研究編輯｜AI 協助製作｜技術來源查核：2026 年 11 月 2 日。本文未經具名專家獨立審閱。