# API Conventions

> API 設計慣例。定義 RESTful 規範、錯誤格式、分頁策略等。 PM、Architect、Backend Dev、QA Reviewer 應注入此 skill。

- Skill: `maxyeh0817/api-conventions` (Agent Skill)
- Install (CLI): `npx skillmds@latest add maxyeh0817/api-conventions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/maxyeh0817/api-conventions/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: maxyeh0817 (https://skillmd.com/u/maxyeh0817)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/maxyeh0817/api-conventions

---


# API Conventions 規範

## RESTful 慣例
- 資源命名：複數名詞（`/users`, `/todos`）
- HTTP 方法語義：
  - `GET` — 讀取（無副作用）
  - `POST` — 創建
  - `PUT` — 全量更新
  - `PATCH` — 部分更新
  - `DELETE` — 刪除
- URL 路徑：kebab-case（`/user-profiles`）
- 巢狀資源：最多兩層（`/users/:id/todos`）

## 狀態碼
- `200` — 成功
- `201` — 創建成功
- `204` — 刪除成功（無回應體）
- `400` — 請求格式錯誤
- `401` — 未認證
- `403` — 無權限
- `404` — 資源不存在
- `422` — 驗證失敗
- `500` — 伺服器內部錯誤

## 錯誤格式
```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "人類可讀的錯誤描述",
    "details": [
      { "field": "email", "message": "格式不正確" }
    ]
  }
}
```

## 分頁策略
- 預設採用 cursor-based 分頁
- 請求參數：`?cursor={cursor}&limit={limit}`
- 回應格式：
```json
{
  "data": [],
  "pagination": {
    "next_cursor": "abc123",
    "has_more": true
  }
}
```
- 預設 limit: 20，最大 limit: 100

## 版本策略
- URL path versioning（`/api/v1/...`）
- 只在破壞性變更時升版

## 已知注意事項
（由 QA 迭代時追加）

> 詳細模式參考：references/patterns.md
> 歷史教訓：references/lessons.md