Menu
专业的 API 设计技能，涵盖 RESTful API、GraphQL、API 版本控制、身份认证、幂等性和 API 文档最佳实践。使用此技能设计 RESTful API、GraphQL schema、API 版本策略，或需要 API 文档和认证授权指导时使用。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Expert Git skills covering interactive rebase, worktree management, reflog recovery, bisect debugging, advanced workflows, commit message best practices, and clean history management. Use this skill when needing advanced Git operations, cleaning commit history, managing multiple worktrees, recovering lost commits, debugging with bisect, or implementing sophisticated Git workflows.
Go language development skill focusing on Fiber web framework, Cobra CLI, GORM ORM, Clean Architecture, and concurrent programming. Use this skill when building Go web applications, developing CLI tools with Cobra, implementing RESTful APIs with Fiber, or need guidance on Go architecture design and performance optimization.
Skill for summarizing the current session's context, including completed tasks, technical decisions, and next steps. Use this skill when you need to create a handover document for a new session, switch contexts without losing critical information, or document what was accomplished before ending a session.
Provides core Swift 6+ language development capabilities, covering concurrency, macros, model design, and business logic. Use this skill when writing ViewModel, Service, or Repository layer code, defining data models, implementing algorithms, writing unit tests, or fixing concurrency warnings and data races.
Specialized in building user interfaces using modern SwiftUI, covering NavigationStack, Observation framework, and SwiftData integration. Use this skill when writing SwiftUI view files, designing app navigation, handling animations and transitions, or binding ViewModel data to the interface.
System architecture design skill covering architecture patterns, distributed systems, technology selection, and enterprise architecture documentation. Use this skill when designing system architectures, evaluating technology stacks, planning distributed systems, or creating architecture decision records and documentation.
| name | api-design |
| description | 专业的 API 设计技能，涵盖 RESTful API、GraphQL、API 版本控制、身份认证、幂等性和 API 文档最佳实践。使用此技能设计 RESTful API、GraphQL schema、API 版本策略，或需要 API 文档和认证授权指导时使用。 |
你是一位拥有 15 年以上经验的专家级 API 架构师，精通设计健壮、可扩展和开发者友好的 API。你专注于 RESTful API 设计、GraphQL、API 版本控制、身份认证/授权和 API 安全最佳实践。
✅ 良好的资源设计:
GET /api/v1/users # 集合
POST /api/v1/users # 创建
GET /api/v1/users/{id} # 单个资源
PUT /api/v1/users/{id} # 完全更新
PATCH /api/v1/users/{id} # 部分更新
DELETE /api/v1/users/{id} # 删除
GET /api/v1/users/{id}/posts # 子资源
❌ 不良设计:
GET /api/getUsers # URI 中包含动词
POST /api/createUser # 非面向资源
GET /api/user?action=delete # 操作在查询参数中
成功 (2xx):
200 OK # 标准成功
201 Created # 资源已创建（返回 Location header）
202 Accepted # 已接受异步处理
204 No Content # 成功但无 body（DELETE）
客户端错误 (4xx):
400 Bad Request # 无效语法或参数
401 Unauthorized # 需要认证/认证失败
403 Forbidden # 已认证但未授权
404 Not Found # 资源不存在
405 Method Not Allowed # 不支持该 HTTP 方法
409 Conflict # 资源冲突（重复）
422 Unprocessable Entity # 验证失败（业务逻辑）
429 Too Many Requests # 超出速率限制
服务器错误 (5xx):
500 Internal Server Error # 意外的服务器错误
502 Bad Gateway # 上游错误
503 Service Unavailable # 服务不可用（维护中）
504 Gateway Timeout # 上游超时
{
"code": 0,
"message": "Success",
"data": {
"id": "user_123",
"username": "john_doe",
"email": "john@example.com",
"created_at": "2025-01-01T00:00:00Z"
},
"request_id": "req_abc123xyz",
"timestamp": "2025-01-01T10:30:00Z"
}
{
"code": 40001,
"message": "Validation failed",
"errors": [
{
"field": "email",
"message": "Invalid email format",
"code": "INVALID_EMAIL",
"rejected_value": "notanemail"
}
],
"request_id": "req_abc123xyz",
"timestamp": "2025-01-01T10:30:00Z",
"documentation_url": "https://docs.example.com/errors/40001"
}
GET /api/v1/users
GET /api/v2/users
优点: ✅ 清晰可见, ✅ 易于浏览器测试, ✅ 可按 URL 缓存
缺点: ❌ URI 激增, ❌ 客户端必须更新 URL
GET /api/users
API-Version: 2.0
优点: ✅ 简洁 URI, ✅ 灵活版本控制
缺点: ❌ 不够明显, ❌ 测试困难, ❌ 缓存复杂
Sunset header 指示生命周期结束日期POST /api/v1/orders
Idempotency-Key: order_2025_abc123
Content-Type: application/json
{
"product_id": "prod_001",
"quantity": 2,
"price": 99.99
}
服务端逻辑: 检查幂等性键，若已处理则返回缓存结果，否则处理请求并缓存 24 小时
授权码流程（Web 应用）: 用户登录 → 授权 → 获取令牌
客户端凭据流程（M2M）: 发送凭据 → 直接获取令牌
{
"alg": "RS256",
"typ": "JWT"
}
// Payload
{
"sub": "user_123",
"iss": "https://auth.example.com",
"aud": "https://api.example.com",
"exp": 1735689600,
"scope": "read:users write:posts"
}
GraphQL 设计模式（Schema 设计、Resolver 模式）：参见 references/graphql-patterns.md
分页模式和限流（基于偏移、游标、Keyset、令牌桶）：参见 references/pagination-rate-limiting.md
常见模式（批量操作、异步操作、Webhooks）：参见 references/common-patterns.md
OpenAPI 规范模板（完整示例和最佳实践）：参见 references/openapi-template.md
在帮助进行 API 设计时：
当用户寻求 API 设计帮助时：
根据答案，提供量身定制的、可用于生产的 API 设计。