AgentSkillsCN

api-development

何时自动调用：创建 API 路由、构建端点、添加 route.ts 文件、实现 REST/GraphQL API、为 API 添加身份验证、实施速率限制、使用 Zod 进行 API 验证，以及处理 HTTP 方法（GET/POST/PUT/DELETE）。 何时不调用：纯前端工作、样式调整、无 API 调用的 React 组件、仅限文档编写的任务，以及未伴随 API 变更的数据库迁移。

SKILL.md
--- frontmatter
name: api-development
description: |
  WHEN to auto-invoke: Creating API routes, building endpoints, adding route.ts files, implementing REST/GraphQL APIs, adding authentication to APIs, rate limiting, API validation with Zod, handling HTTP methods (GET/POST/PUT/DELETE).
  WHEN NOT to invoke: Pure frontend work, styling, React components without API calls, documentation-only tasks, database migrations without API changes.

API Development Skill

You are an expert in building production-ready REST APIs with Next.js App Router.

Capabilities

Route Creation

  • •App Router API routes (app/api/*/route.ts)
  • •Proper HTTP method handlers (GET, POST, PUT, PATCH, DELETE)
  • •Request/response typing with TypeScript
  • •Edge Runtime compatibility when needed

Validation & Error Handling

  • •Zod schema validation for all inputs
  • •Structured error responses with proper HTTP status codes
  • •Input sanitization and type coercion
  • •Comprehensive error messages for debugging

Authentication & Authorization

  • •JWT and session-based auth patterns
  • •Middleware-based protection
  • •Role-based access control (RBAC)
  • •API key authentication for external services

Rate Limiting

  • •Upstash Redis rate limiting
  • •Sliding window and fixed window strategies
  • •IP-based and user-based limiting
  • •Graceful degradation

Testing

  • •API route unit tests with Jest/Vitest
  • •Integration tests with supertest patterns
  • •Mock strategies for external services
  • •Test coverage for edge cases

Best Practices

  1. •Validate Early: Use Zod at route entry points
  2. •Type Everything: Never use any types
  3. •Handle Errors Consistently: Use structured error format
  4. •Document Inline: JSDoc comments for complex logic
  5. •Consider Edge Runtime: Avoid Node.js-specific APIs when possible

Response Format

typescript
// Success
{ data: T, meta?: { pagination, etc } }

// Error
{ error: { code: string, message: string, details?: unknown } }

Integration Points

  • •Supabase for database operations
  • •NextAuth.js for authentication
  • •Upstash for rate limiting and caching
  • •Zod for validation schemas