RESTful API 是一種遵循 REST（表述性狀態轉移）架構風格設計的網路服務介面，強調以資源為中心、使用標準 HTTP 方法、無狀態通訊與一致介面，讓用戶端與伺服端鬆耦合、可擴展且易於維護。
核心約束- 客戶端-伺服端分離：前後端職責分離，可獨立演進，只需遵守約定的資源契約與格式。
- 無狀態：每個請求都須攜帶完成處理所需資訊，伺服端不保存會話狀態，提升可擴展性與容錯性。
- 可快取：回應需明確標示可否快取與有效期，以降低延遲與伺服壓力。
- 分層系統：客戶端不需知道是否經過中介層（閘道、快取、負載平衡、驗證），有助安全與伸縮。
- 一致介面：資源以 URI 識別；以標準方法操作（GET/POST/PUT/PATCH/DELETE）；訊息自我描述；可選用 HATEOAS 提供超連結導引後續動作。
- 按需下載程式碼（可選）：伺服端可回傳可執行程式碼以擴展用戶端行為（較少在API中使用）。
資源導向設計
- 資源命名：以名詞與階層化路徑表示，例如 /users、/users/{id}、/orders/{id}/items。
- 標準方法與語意：
- GET 讀取資源（安全且冪等）
- POST 建立資源或執行非冪等動作
- PUT 以完整表示更新（冪等）
- PATCH 局部更新
- DELETE 刪除（冪等）。
- 回應碼與標頭：合理使用 2xx/4xx/5xx；Location 指向新資源；ETag/Last-Modified 支援條件式請求與快取。
回應格式與契約
- 常用 JSON（或 XML/CSV 等），明確 Content-Type、Accept；版本化可用 Accept 版本或 URI 前綴（/v1）。
- 文件化：以 OpenAPI/Swagger 描述端點、參數與回應，提升可用性與一致性。
設計最佳實踐
- 冪等與重試：確保 PUT/DELETE 冪等；設定超時、退避重試與錯誤分類。
- 分頁/篩選/排序：提供 query 參數（如 page、limit、sort、filter），並在回應提供分頁中繼資訊與連結。
- 安全性：全站 TLS；OAuth2/OIDC/JWT；最小權限；輸入驗證與速率限制；審計記錄。
- 可觀測性：結構化日誌、追蹤ID（Correlation-Id）、標準化錯誤格式、度量與告警。
- 版本治理：語義化變更策略，避免破壞性更新；提供遷移期與棄用公告。
何時不選 REST
- 強流程、雙向串流、低延遲推送：考慮 gRPC、WebSocket。
- 需要查詢彈性與聚合減少過/少取數：考慮 GraphQL。
- 事件驅動整合：採用事件流/訊息匯流排（如 Kafka），以 REST 作為查詢介面。
簡言之，RESTful API 透過資源導向與標準化 HTTP 互動，實現鬆耦合、可擴展、可快取與易治理的服務介面；遵循無狀態、一致介面、分層與快取等關鍵約束與最佳實踐，是現代後端與系統整合的主流設計範式。
