# API Design

生产级 API 的 REST API 设计模式，包括资源命名、状态码、分页、过滤、错误响应、版本控制和速率限制。

- Repository: https://github.com/xu-xiang/everything-claude-code-zh (2012 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-03-05
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add xu-xiang/everything-claude-code-zh --skill api-design -g -a claude-code -y`
Codex: `npx skills add xu-xiang/everything-claude-code-zh --skill api-design -g -a codex -y`
Cursor: `npx skills add xu-xiang/everything-claude-code-zh --skill api-design -g -a cursor -y`
Gemini CLI: `npx skills add xu-xiang/everything-claude-code-zh --skill api-design -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add xu-xiang/everything-claude-code-zh`

## Description

生产级 API 的 REST API 设计模式，包括资源命名、状态码、分页、过滤、错误响应、版本控制和速率限制。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# API 设计模式（API Design Patterns）

用于设计一致且开发者友好的 REST API 的约定与最佳实践。

## 何时激活（When to Activate）

- 设计新的 API 端点（Endpoint）
- 审查现有的 API 合约
- 添加分页、过滤或排序功能
- 为 API 实现错误处理
- 规划 API 版本化策略
- 构建公开或面向合作伙伴的 API

## 资源设计（Resource Design）

### URL 结构

```
# 资源应为名词、复数、小写、短横线命名法（kebab-case）
GET    /api/v1/users
GET    /api/v1/users/:id
POST   /api/v1/users
PUT    /api/v1/users/:id
PATCH  /api/v1/users/:id
DELETE /api/v1/users/:id

# 关系的子资源
GET    /api/v1/users/:id/orders
POST   /api/v1/users/:id/orders

# 不符合 CRUD 的操作（谨慎使用动词）
POST   /api/v1/orders/:id/cancel
POST   /api/v1/auth/login
POST   /api/v1/auth/refresh
```

### 命名规则

```
# 推荐（GOOD）
/api/v1/team-members          # 多词资源使用短横线命名法（kebab-case）
/api/v1/orders?status=active  # 使用查询参数进行过滤
/api/v1/users/123/orders      # 嵌套资源表示归属关系

# 错误（BAD）
/api/v1/getUsers              # URL 中包含动词
/api/v1/user                  # 使用单数（应使用复数）
/api/v1/team_members          # URL 中使用蛇形命名法（snake_case）
/api/v1/users/123/getOrders   # 嵌套资源中包含动词
```

## HTTP 方法与状态码（HTTP Methods and Status Codes）

### 方法语义

| 方法 | 幂等性（Idempotent） | 安全性（Safe） | 用途 |
|--------|-----------|------|---------|
| GET | 是 | 是 | 获取资源 |
| POST | 否 | 否 | 创建资源，触发操作 |
| PUT | 是 | 否 | 完整替换资源 |
| PATCH | 否* | 否 | 部分更新资源 |
| DELETE | 是 | 否 | 删除资源 |

*通过正确的实现，PATCH 也可以设计为幂等。

### 状态码参考

```
# 成功（Success）
200 OK, GET, PUT, PATCH（包含响应体）
201 Created, POST（需包含 Location 响应头）
204 No Content, DELETE, PUT（不含响应体）

# 客户端错误（Client Errors）
400 Bad Request, 校验失败，JSON 格式错误
401 Unauthorized, 缺失或无效的身份验证
403 Forbidden, 已验证身份但未获得授权
404 Not Found, 资源不存在
409 Conflict, 重复条目，状态冲突
422 Unprocessable Entity, 语义错误（JSON 正确但数据非法）
429 Too Many Requests, 超出速率限制

# 服务端错误（Server Errors）
500 Internal Server Error, 意外错误（绝不要暴露详细堆栈）
502 Bad Gateway, 上游服务失败
503 Service Unavailable, 暂时性过载，需包含 Retry-After
```

### 常见错误

```
# 错误：所有响应都返回 200
{ "status": 200, "success": false, "error": "Not found" }

The rest: https://github.com/xu-xiang/everything-claude-code-zh/blob/HEAD/.agents/skills/api-design/SKILL.md