# API Patterns

> API 設計原則與決策。REST vs GraphQL vs tRPC 選擇、回應格式、版本控制、分頁。

- Skill: `tai-ch0802/api-patterns` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add tai-ch0802/api-patterns`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tai-ch0802/api-patterns/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: Tai-ch0802 (https://skillmd.com/u/tai-ch0802)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/tai-ch0802/api-patterns

---


# API 模式

> API 設計原則與 2025 年最佳決策。
> **學習思考方式，而非複製固定模式。**

## 🎯 選擇性閱讀規則

**僅閱讀與需求相關的檔案！** 查看內容地圖，找到你需要的。

---

## 📑 內容地圖

| 檔案 | 描述 | 何時閱讀 |
|------|------|----------|
| `api-style.md` | REST vs GraphQL vs tRPC 決策樹 | 選擇 API 類型 |
| `rest.md` | 資源命名、HTTP 方法、狀態碼 | 設計 REST API |
| `response.md` | 封裝模式、錯誤格式、分頁 | 回應結構 |
| `graphql.md` | Schema 設計、使用時機、安全性 | 考慮 GraphQL |
| `trpc.md` | TypeScript monorepo、型別安全 | TS 全端專案 |
| `versioning.md` | URI/Header/Query 版本控制 | API 演進規劃 |
| `auth.md` | JWT、OAuth、Passkey、API Keys | 驗證模式選擇 |
| `rate-limiting.md` | Token bucket、滑動視窗 | API 保護 |
| `documentation.md` | OpenAPI/Swagger 最佳實踐 | 文件撰寫 |
| `security-testing.md` | OWASP API Top 10、驗證/授權測試 | 安全稽核 |

---

## 🔗 相關技能

| 需求 | 技能 |
|------|------|
| API 實作 | `@[skills/backend-development]` |
| 資料結構 | `@[skills/database-design]` |
| 安全細節 | `@[skills/security-hardening]` |

---

## ✅ 決策檢查清單

設計 API 前：

- [ ] **是否詢問過使用者 API 的消費者？**
- [ ] **是否根據此情境選擇了 API 風格？**（REST/GraphQL/tRPC）
- [ ] **是否定義了一致的回應格式？**
- [ ] **是否規劃了版本控制策略？**
- [ ] **是否考慮了驗證需求？**
- [ ] **是否規劃了速率限制？**
- [ ] **是否定義了文件方法？**

---

## ❌ 反模式

**不要：**
- 所有情況預設使用 REST
- 在 REST 端點中使用動詞（/getUsers）
- 回傳不一致的回應格式
- 將內部錯誤暴露給客戶端
- 跳過速率限制

**要：**
- 根據情境選擇 API 風格
- 詢問客戶端需求
- 撰寫完整文件
- 使用適當的狀態碼

---

## 腳本

| 腳本 | 用途 | 指令 |
|------|------|------|
| `scripts/api_validator.py` | API 端點驗證 | `python scripts/api_validator.py <project_path>` |