API 的全名是 Application Programming Interface，中文翻譯為「應用程式介面」，簡單來說就是一個介面，讓不同的程式可以互相溝通。

而 RESTful API 是一種 API 的設計風格，REST 的全名是 Representational State Transfer，中文翻譯為「具象狀態轉移」。

RESTful API 的特色

  1. 無狀態性 (Stateless)：每個請求都應該包含處理該請求所需的所有資訊，伺服器不會儲存任何客戶端的狀態資訊。

  2. 統一介面 (Uniform Interface)：所有的資源都透過相同的介面進行操作，主要包含：

    • 資源識別：透過 URI 來識別資源
    • 資源操作：透過 HTTP 方法來操作資源
    • 自我描述的訊息：每個訊息都包含如何處理該訊息的足夠資訊
    • 超媒體作為應用程式狀態的引擎

  3. 客戶端-伺服器架構 (Client-Server)：將使用者介面與資料儲存分離，提高了系統的可移植性。

HTTP 方法與 CRUD 操作的對應

HTTP 方法 CRUD 操作 說明
GET Read 取得資源
POST Create 建立資源
PUT Update 更新整個資源
PATCH Update 部分更新資源
DELETE Delete 刪除資源

RESTful API 的 URL 設計原則

  1. 使用名詞而非動詞

    • 好：GET /users/123
    • 壞：GET /getUser/123

  2. 使用複數名詞

    • 好：GET /users
    • 壞：GET /user

  3. 使用階層結構表示資源關係

    • GET /users/123/posts - 取得用戶 123 的所有文章
    • GET /users/123/posts/456 - 取得用戶 123 的文章 456

  4. 使用查詢參數進行過濾、排序和分頁

    • GET /users?age=25&sort=name&page=2

HTTP 狀態碼

RESTful API 應該回傳適當的 HTTP 狀態碼：

  • 2xx 成功

    • 200 OK：請求成功
    • 201 Created：資源已建立
    • 204 No Content：請求成功但沒有回傳內容

  • 4xx 客戶端錯誤

    • 400 Bad Request：請求格式錯誤
    • 401 Unauthorized：未授權
    • 404 Not Found：資源不存在

  • 5xx 伺服器錯誤

    • 500 Internal Server Error：伺服器內部錯誤