From bb-spec-backend
REST API design patterns including resource naming, status codes, pagination, filtering, error responses with structured A-BBB-CCCC error codes, versioning, and rate limiting for production APIs.
How this skill is triggered — by the user, by Claude, or both
Slash command
/bb-spec-backend:api-designThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
设计新 API 端点、审查 API 契约、实现分页/过滤/排序、处理 API 错误、规划版本策略。
设计新 API 端点、审查 API 契约、实现分页/过滤/排序、处理 API 错误、规划版本策略。
/api/v1/team-members/api/v1/users/:id/ordersPOST /api/v1/orders/:id/cancel/getUsers)、单数资源名、snake_case| Method | 幂等 | 用途 |
|---|---|---|
| GET | 是 | 读取 |
| POST | 否 | 创建、触发动作 |
| PUT | 是 | 整体替换 |
| PATCH | 否* | 部分更新 |
| DELETE | 是 | 删除 |
成功:200(GET/PUT/PATCH)、201+Location(POST 创建)、204(DELETE/无 body) 客户端错误:400 校验失败、401 未认证、403 无权限、404 不存在、409 冲突、422 语义无效、429 限流 服务端错误:500 内部错误(不暴露细节)、502 上游失败、503 暂不可用(带 Retry-After)
禁止:200 包一切({"success":false})、500 表示校验错误。
单资源:直接返回资源对象,禁止 data 包装。
{ "id": "abc", "name": "...", "created_at": "..." }
集合(带分页):
{
"items": [...],
"meta": { "total": 142, "page": 1, "per_page": 20, "total_pages": 8 },
"links": { "self": "...", "next": "...", "last": "..." }
}
错误:
{
"error": {
"code": "1-001-0001",
"message": "Request validation failed",
"details": [{ "field": "email", "message": "Must be valid" }]
}
}
错误码格式 A-BBB-CCCC:A = 来源(1 用户端 / 2 系统 / 3 第三方),BBB = 三位模块号,CCCC = 四位模块内编号。error.code 只允许此格式;禁止自由格式(validation_error 等语义字符串)、跨模块复用编号、两套错误码体系并存。
| 场景 | 方式 |
|---|---|
| 后台管理、小数据集 (<10K) | Offset:?page=2&per_page=20 |
| 无限滚动、大数据集、公共 API | Cursor:?cursor=xxx&limit=20(多查一条判断 has_next) |
?status=active&price[gte]=10&price[lte]=100?sort=-created_at,price(- 前缀降序)?q=wireless+headphones?fields=id,name,emailAuthorization: Bearer <token>X-API-Key: sk_live_xxx响应头:X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset
超限返回 429 + Retry-After。
| 层级 | 限额 | 维度 |
|---|---|---|
| 匿名 | 30/min | Per IP |
| 认证用户 | 100/min | Per user |
| 付费 | 1000/min | Per API key |
| 内部服务 | 10000/min | Per service |
推荐 URL 路径版本:/api/v1/users。最多维护 2 个活跃版本。
非破坏性变更(不需要新版本):新增响应字段、新增可选参数、新增端点。 破坏性变更(需要新版本):删除/重命名字段、改类型、改 URL 结构、改认证方式。
error.code 用 A-BBB-CCCC)Provides CDSS development patterns for drug interaction checking, dose validation, clinical scoring (NEWS2, qSOFA), and alert classification integrated into EMR workflows.
npx claudepluginhub 0xbb2b/bb-spec --plugin bb-spec-backend