9.RESTful_API.md

last update: 2025-06-07

REST（Representational State Transfer）是一種設計 Web API 的架構風格，透過 HTTP 協定上的標準方法來進行資源的存取與操作。

---

REST 特性

1. 使用標準 HTTP 方法（GET, POST, PUT, DELETE）

2. 每個資源有唯一 URI（資源路徑）

3. 無狀態設計（Stateless）：每次請求皆獨立處理

4. 支援多種格式：常見為 JSON，也可使用 XML、HTML 等

5. 分層結構（Layered System）

---

HTTP 方法對應語意

方法	說明	範例用途
GET	讀取資源	查詢用戶資訊
POST	建立新資源	新增留言
PUT	更新整筆資源	修改設定檔
PATCH	部分更新資源	更新名稱欄位
DELETE	刪除資源	移除文章

---

RESTful URI 設計

• /users：取得所有使用者（GET）

• /users/123：取得 id 為 123 的使用者（GET）

• /users：新增使用者（POST）

• /users/123：修改使用者（PUT/PATCH）

• /users/123：刪除使用者（DELETE）

不建議：

GET /getUserById?id=123
POST /deleteUser

應避免在 URI 中使用動詞，應使用資源名詞配合 HTTP 方法。

---

FastAPI 實作範例

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):
    name: str
    email: str

fake_db = {}

@app.get("/users")
def list_users():
    return list(fake_db.values())

@app.post("/users")
def create_user(user: User):
    uid = len(fake_db) + 1
    fake_db[uid] = user
    return {"id": uid, **user.dict()}

@app.get("/users/{user_id}")
def get_user(user_id: int):
    return fake_db.get(user_id, {})

@app.delete("/users/{user_id}")
def delete_user(user_id: int):
    fake_db.pop(user_id, None)
    return {"ok": True}

---

小結

原則	說明
URI 使用名詞	每個資源皆具唯一 URI 標識
動作由 HTTP 方法決定	GET/POST/PUT/DELETE 等
無狀態設計	每次請求獨立處理，不依賴伺服器記憶

RESTful API 設計簡潔、可讀性高，便於維護與擴充，現今是主流的 Web API 設計方式之一。