api-design

What this skill does

When applied, it prepends a system prompt before your request is sent — no extra calls and no change to how you are billed beyond the added tokens.

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

# API 设计模式

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

## 何时启用

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

## 资源设计

### URL 结构

```
# 资源使用名词、复数、小写、短横线连接
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
```

### 命名规则

```
# 良好
/api/v1/team-members          # 多单词资源使用 kebab-case
/api/v1/orders?status=active  # 查询参数用于过滤
/api/v1/users/123/orders      # 嵌套资源表示所有权关系

# 不良
/api/v1/getUsers              # URL 中包含动词
/api/v1/user                  # 使用单数形式（应使用复数）
/api/v1/team_members          # URL 中使用 snake_case
/api/v1/users/123/getOrders   # 嵌套资源路径中包含动词
```

## HTTP 方法和状态码

### 方法语义

| 方法 | 幂等性 | 安全性 | 用途 |
|--------|-----------|------|---------|
| GET | 是 | 是 | 检索资源 |
| POST | 否 | 否 | 创建资源，触发操作 |
| PUT | 是 | 否 | 完全替换资源 |
| PATCH | 否\* | 否 | 部分更新资源 |
| DELETE | 是 | 否 | 删除资源 |

\*通过适当的实现，PATCH 可以实现幂等

### 状态码参考

```
# 成功
200 OK                    — GET、PUT、PATCH（包含响应体）
201 Created               — POST（包含 Location 头部）
204 No Content            — DELETE、PUT（无响应体）

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

# 服务器错误
500 Internal Server Error — 意外故障（切勿暴露细节）
502 Bad Gateway           — 上游服务失败
503 Service Unavailable   — 临时过载，需包含 Retry-After 头部
```

### 常见错误

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

# 正确：按语义使用 HTTP 状态码
HTTP/1.1 404 Not Found
{ "error": { "code": "not_found", "message"

Use this skill

{
  "model": "gpt-4o-mini",
  "skill": "imp-eaea4a27-6b4e-4741-8c9a-5019435b6222",
  "messages": [{ "role": "user", "content": "…" }]
}

More skills