api-design-principles

本技能為設計專業級 API 提供了完整的框架，重點在於業界標準模式，如 RESTful 資源導向架構與 GraphQL Schema-first 開發。適用於後端工程師、系統架構師與技術主管，他們需要建立 API 設計標準、進行設計審查或重構現有介面以提升可用性與維護性。無論是構建新服務或在不同典範間遷移，本技能都能確保您的 API 保持直觀、高效且對開發者友善。

• 資源導向架構：應用名詞作為資源，並正確使用 HTTP 動詞語義（GET, POST, PUT, PATCH, DELETE）來維持一致的 API 行為。

• GraphQL 精通：實作 Schema-first 設計、高效的查詢結構、變更（Mutations）與訂閱（Subscriptions），以實現精確的客戶端資料獲取。

• 版本控制策略：實作健全的 URL、Header 或 Query 參數版本控制，以確保向後相容性與平滑的轉換。

• 進階模式：應用 HATEOAS、分頁、篩選，以及使用 HTTP 狀態碼進行標準化的錯誤處理，以改善客戶端整合與除錯流程。

• 文件標準：創建自解釋性 API，強調清晰度、強型別與直觀的層級，為第三方開發者提供絕佳體驗。

• 在專案的架構設計階段、撰寫端點邏輯或定義資料模型前使用此技能。

• 非常適合審查現有規範，以識別諸如以動作為導向的命名或不一致的錯誤回應等常見陷阱。

• 支援基於 Pydantic 的驗證與 FastAPI 風格的實作模式，將設計原則轉化為高品質代碼。

• 輸入通常包括技術需求、領域模型或有問題的現有端點；輸出則是精煉後的 API 規範、設計模式或給開發者的結構化回饋。

• 約束：專注於後端 API 設計；請確保在維持此處提供的通用設計原則同時，遵守您特定框架（如 FastAPI, Apollo）的要求。