菜单
REST and GraphQL API design conventions including URL patterns, status codes, pagination, error format, and versioning. Use when designing new APIs, reviewing API contracts, or adding endpoints to any backend.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | api-design |
| description | REST and GraphQL API design conventions including URL patterns, status codes, pagination, error format, and versioning. Use when designing new APIs, reviewing API contracts, or adding endpoints to any backend. |
| metadata | {"version":"1.0"} |
New API needed → What type?
├─ CRUD operations on resources → REST
├─ Complex queries, multiple resources in one call → GraphQL
├─ Real-time updates → WebSocket or SSE
├─ Internal microservice → gRPC or REST
└─ Simple webhook/callback → REST POST
GET /resources # List (with pagination)
GET /resources/:id # Get one
POST /resources # Create
PUT /resources/:id # Full replace
PATCH /resources/:id # Partial update
DELETE /resources/:id # Delete
# Nested resources (one level max)
GET /users/:id/posts # User's posts
# Actions (when CRUD doesn't fit)
POST /resources/:id/actions/publish
Rules:
| Code | When |
|---|---|
| 200 | Success with body |
| 201 | Created (POST) |
| 204 | Success, no body (DELETE) |
| 400 | Invalid request data |
| 401 | Not authenticated |
| 403 | Authenticated but not authorized |
| 404 | Not found |
| 409 | Conflict (duplicate, state conflict) |
| 422 | Validation error |
| 429 | Rate limited |
| 500 | Server error |
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Human-readable explanation",
"details": [
{ "field": "email", "message": "must be a valid email address" }
]
}
}
# Offset-based (simple)
GET /resources?page=2&per_page=20
# Cursor-based (preferred for large datasets)
GET /resources?cursor=abc123&limit=20
| Anti-Pattern | Fix |
|---|---|
Verbs in URLs (/getUsers) | HTTP methods (GET /users) |
Singular nouns (/user/1) | Plural (/users/1) |
Deep nesting (/a/1/b/2/c/3) | Max one level, use query params |
| 200 with error body | Use proper status codes |
| No pagination on lists | Always paginate, default limit |
| Exposing auto-increment IDs | UUIDs for public APIs |
Web accessibility checklist covering WCAG guidelines, ARIA patterns, keyboard navigation, color contrast, screen reader support, and form accessibility. Use when building UI components, reviewing frontend code, or when accessibility is mentioned.
When to refactor vs leave alone, code smell detection, safe refactoring steps, and common transformation patterns. Use when asked to refactor code, clean up technical debt, or when reviewing code that shows structural problems.
Authentication and authorization patterns including JWT vs sessions, OAuth flows, token refresh, RBAC, and password handling. Use when implementing login, signup, token management, role-based access, or reviewing auth security.
Structured research methodology with scoping, multi-source collection, triangulation, source credibility scoring, and anti-hallucination guards. Use when investigating technologies, comparing tools, evaluating libraries, exploring unfamiliar codebases, or producing research reports.
Build MCP (Model Context Protocol) servers in TypeScript or Python. Use when creating custom tools, resources, or prompts that extend AI assistant capabilities via MCP.
Structured logging patterns, log levels, trace IDs, and what to log vs what never to log. Use when setting up logging, choosing log levels, implementing request tracing, or reviewing log output quality.