Back to Details

api-endpoint-builder

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

API Endpoint Builder

API 端点构建工具

Build complete, production-ready REST API endpoints with proper validation, error handling, authentication, and documentation.
构建完整的、可用于生产环境的 REST API 端点，包含规范的校验逻辑、错误处理、身份认证和文档。

When to Use This Skill

何时使用此技能

  • User asks to "create an API endpoint" or "build a REST API"
  • Building new backend features
  • Adding endpoints to existing APIs
  • User mentions "API", "endpoint", "route", or "REST"
  • Creating CRUD operations
  • 用户要求「创建API端点」或「构建REST API」时
  • 开发新的后端功能时
  • 为现有API新增端点时
  • 用户提到「API」、「endpoint」、「route」或「REST」时
  • 开发CRUD操作时

What You'll Build

你将构建的内容

For each endpoint, you create:
  • Route handler with proper HTTP method
  • Input validation (request body, params, query)
  • Authentication/authorization checks
  • Business logic
  • Error handling
  • Response formatting
  • API documentation
  • Tests (if requested)
为每个端点创建以下内容：
  • 带有正确HTTP方法的路由处理程序
  • 输入校验（请求体、路径参数、查询参数）
  • 身份认证/授权校验
  • 业务逻辑
  • 错误处理
  • 响应格式化
  • API文档
  • 测试（如果有要求）

Endpoint Structure

端点结构

1. Route Definition

1. 路由定义

javascript
// Express example
router.post('/api/users', authenticate, validateUser, createUser);

// Fastify example
fastify.post('/api/users', {
  preHandler: [authenticate],
  schema: userSchema
}, createUser);
javascript
// Express example
router.post('/api/users', authenticate, validateUser, createUser);

// Fastify example
fastify.post('/api/users', {
  preHandler: [authenticate],
  schema: userSchema
}, createUser);

2. Input Validation

2. 输入校验

Always validate before processing:
javascript
const validateUser = (req, res, next) => {
  const { email, name, password } = req.body;
  
  if (!email || !email.includes('@')) {
    return res.status(400).json({ error: 'Valid email required' });
  }
  
  if (!name || name.length < 2) {
    return res.status(400).json({ error: 'Name must be at least 2 characters' });
  }
  
  if (!password || password.length < 8) {
    return res.status(400).json({ error: 'Password must be at least 8 characters' });
  }
  
  next();
};
处理请求前始终先做校验：
javascript
const validateUser = (req, res, next) => {
  const { email, name, password } = req.body;
  
  if (!email || !email.includes('@')) {
    return res.status(400).json({ error: 'Valid email required' });
  }
  
  if (!name || name.length < 2) {
    return res.status(400).json({ error: 'Name must be at least 2 characters' });
  }
  
  if (!password || password.length < 8) {
    return res.status(400).json({ error: 'Password must be at least 8 characters' });
  }
  
  next();
};

3. Handler Implementation

3. 处理程序实现

javascript
const createUser = async (req, res) => {
  try {
    const { email, name, password } = req.body;
    
    // Check if user exists
    const existing = await db.users.findOne({ email });
    if (existing) {
      return res.status(409).json({ error: 'User already exists' });
    }
    
    // Hash password
    const hashedPassword = await bcrypt.hash(password, 10);
    
    // Create user
    const user = await db.users.create({
      email,
      name,
      password: hashedPassword,
      createdAt: new Date()
    });
    
    // Don't return password
    const { password: _, ...userWithoutPassword } = user;
    
    res.status(201).json({
      success: true,
      data: userWithoutPassword
    });
    
  } catch (error) {
    console.error('Create user error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
};
javascript
const createUser = async (req, res) => {
  try {
    const { email, name, password } = req.body;
    
    // Check if user exists
    const existing = await db.users.findOne({ email });
    if (existing) {
      return res.status(409).json({ error: 'User already exists' });
    }
    
    // Hash password
    const hashedPassword = await bcrypt.hash(password, 10);
    
    // Create user
    const user = await db.users.create({
      email,
      name,
      password: hashedPassword,
      createdAt: new Date()
    });
    
    // Don't return password
    const { password: _, ...userWithoutPassword } = user;
    
    res.status(201).json({
      success: true,
      data: userWithoutPassword
    });
    
  } catch (error) {
    console.error('Create user error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
};

Best Practices

最佳实践

HTTP Status Codes

HTTP 状态码

  • 200
    - Success (GET, PUT, PATCH)
  • 201
    - Created (POST)
  • 204
    - No Content (DELETE)
  • 400
    - Bad Request (validation failed)
  • 401
    - Unauthorized (not authenticated)
  • 403
    - Forbidden (not authorized)
  • 404
    - Not Found
  • 409
    - Conflict (duplicate)
  • 500
    - Internal Server Error
  • 200
    - 成功（GET、PUT、PATCH请求）
  • 201
    - 已创建（POST请求）
  • 204
    - 无内容（DELETE请求）
  • 400
    - 请求错误（校验失败）
  • 401
    - 未授权（未完成身份认证）
  • 403
    - 禁止访问（无操作权限）
  • 404
    - 资源不存在
  • 409
    - 冲突（重复资源）
  • 500
    - 服务内部错误

Response Format

响应格式

Consistent structure:
javascript
// Success
{
  "success": true,
  "data": { ... }
}

// Error
{
  "error": "Error message",
  "details": { ... } // optional
}

// List with pagination
{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}
统一结构：
javascript
// Success
{
  "success": true,
  "data": { ... }
}

// Error
{
  "error": "Error message",
  "details": { ... } // optional
}

// List with pagination
{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100
  }
}

Security Checklist

安全检查清单

  • Authentication required for protected routes
  • Authorization checks (user owns resource)
  • Input validation on all fields
  • SQL injection prevention (use parameterized queries)
  • Rate limiting on public endpoints
  • No sensitive data in responses (passwords, tokens)
  • CORS configured properly
  • Request size limits set
  • 受保护路由需要身份认证
  • 授权校验（确认用户拥有对应资源的操作权限）
  • 所有字段都做输入校验
  • 预防SQL注入（使用参数化查询）
  • 公共端点配置限流
  • 响应中不返回敏感数据（密码、令牌）
  • CORS配置正确
  • 设置请求大小限制

Error Handling

错误处理

javascript
// Centralized error handler
app.use((err, req, res, next) => {
  console.error(err.stack);
  
  // Don't leak error details in production
  const message = process.env.NODE_ENV === 'production' 
    ? 'Internal server error' 
    : err.message;
  
  res.status(err.status || 500).json({ error: message });
});
javascript
// Centralized error handler
app.use((err, req, res, next) => {
  console.error(err.stack);
  
  // Don't leak error details in production
  const message = process.env.NODE_ENV === 'production' 
    ? 'Internal server error' 
    : err.message;
  
  res.status(err.status || 500).json({ error: message });
});

Common Patterns

通用模式

CRUD Operations

CRUD 操作

javascript
// Create
POST /api/resources
Body: { name, description }

// Read (list)
GET /api/resources?page=1&limit=20

// Read (single)
GET /api/resources/:id

// Update
PUT /api/resources/:id
Body: { name, description }

// Delete
DELETE /api/resources/:id
javascript
// Create
POST /api/resources
Body: { name, description }

// Read (list)
GET /api/resources?page=1&limit=20

// Read (single)
GET /api/resources/:id

// Update
PUT /api/resources/:id
Body: { name, description }

// Delete
DELETE /api/resources/:id

Pagination

分页

javascript
const getResources = async (req, res) => {
  const page = parseInt(req.query.page) || 1;
  const limit = parseInt(req.query.limit) || 20;
  const skip = (page - 1) * limit;
  
  const [resources, total] = await Promise.all([
    db.resources.find().skip(skip).limit(limit),
    db.resources.countDocuments()
  ]);
  
  res.json({
    success: true,
    data: resources,
    pagination: {
      page,
      limit,
      total,
      pages: Math.ceil(total / limit)
    }
  });
};
javascript
const getResources = async (req, res) => {
  const page = parseInt(req.query.page) || 1;
  const limit = parseInt(req.query.limit) || 20;
  const skip = (page - 1) * limit;
  
  const [resources, total] = await Promise.all([
    db.resources.find().skip(skip).limit(limit),
    db.resources.countDocuments()
  ]);
  
  res.json({
    success: true,
    data: resources,
    pagination: {
      page,
      limit,
      total,
      pages: Math.ceil(total / limit)
    }
  });
};

Filtering & Sorting

筛选与排序

javascript
const getResources = async (req, res) => {
  const { status, sort = '-createdAt' } = req.query;
  
  const filter = {};
  if (status) filter.status = status;
  
  const resources = await db.resources
    .find(filter)
    .sort(sort)
    .limit(20);
  
  res.json({ success: true, data: resources });
};
javascript
const getResources = async (req, res) => {
  const { status, sort = '-createdAt' } = req.query;
  
  const filter = {};
  if (status) filter.status = status;
  
  const resources = await db.resources
    .find(filter)
    .sort(sort)
    .limit(20);
  
  res.json({ success: true, data: resources });
};

Documentation Template

文档模板

javascript
/**
 * @route POST /api/users
 * @desc Create a new user
 * @access Public
 * 
 * @body {string} email - User email (required)
 * @body {string} name - User name (required)
 * @body {string} password - Password, min 8 chars (required)
 * 
 * @returns {201} User created successfully
 * @returns {400} Validation error
 * @returns {409} User already exists
 * @returns {500} Server error
 * 
 * @example
 * POST /api/users
 * {
 *   "email": "user@example.com",
 *   "name": "John Doe",
 *   "password": "securepass123"
 * }
 */
javascript
/**
 * @route POST /api/users
 * @desc Create a new user
 * @access Public
 * 
 * @body {string} email - User email (required)
 * @body {string} name - User name (required)
 * @body {string} password - Password, min 8 chars (required)
 * 
 * @returns {201} User created successfully
 * @returns {400} Validation error
 * @returns {409} User already exists
 * @returns {500} Server error
 * 
 * @example
 * POST /api/users
 * {
 *   "email": "user@example.com",
 *   "name": "John Doe",
 *   "password": "securepass123"
 * }
 */

Testing Example

测试示例

javascript
describe('POST /api/users', () => {
  it('should create a new user', async () => {
    const response = await request(app)
      .post('/api/users')
      .send({
        email: 'test@example.com',
        name: 'Test User',
        password: 'password123'
      });
    
    expect(response.status).toBe(201);
    expect(response.body.success).toBe(true);
    expect(response.body.data.email).toBe('test@example.com');
    expect(response.body.data.password).toBeUndefined();
  });
  
  it('should reject invalid email', async () => {
    const response = await request(app)
      .post('/api/users')
      .send({
        email: 'invalid',
        name: 'Test User',
        password: 'password123'
      });
    
    expect(response.status).toBe(400);
    expect(response.body.error).toContain('email');
  });
});
javascript
describe('POST /api/users', () => {
  it('should create a new user', async () => {
    const response = await request(app)
      .post('/api/users')
      .send({
        email: 'test@example.com',
        name: 'Test User',
        password: 'password123'
      });
    
    expect(response.status).toBe(201);
    expect(response.body.success).toBe(true);
    expect(response.body.data.email).toBe('test@example.com');
    expect(response.body.data.password).toBeUndefined();
  });
  
  it('should reject invalid email', async () => {
    const response = await request(app)
      .post('/api/users')
      .send({
        email: 'invalid',
        name: 'Test User',
        password: 'password123'
      });
    
    expect(response.status).toBe(400);
    expect(response.body.error).toContain('email');
  });
});

Key Principles

核心原则

  • Validate all inputs before processing
  • Use proper HTTP status codes
  • Handle errors gracefully
  • Never expose sensitive data
  • Keep responses consistent
  • Add authentication where needed
  • Document your endpoints
  • Write tests for critical paths
  • 处理请求前校验所有输入
  • 使用规范的HTTP状态码
  • 优雅处理错误
  • 永远不要暴露敏感数据
  • 保持响应格式统一
  • 需要的位置添加身份认证
  • 为你的端点编写文档
  • 为核心路径编写测试

Related Skills

相关技能

  • @security-auditor
    - Security review
  • @test-driven-development
    - Testing
  • @database-design
    - Data modeling
  • @security-auditor
    - 安全审计
  • @test-driven-development
    - 测试开发
  • @database-design
    - 数据建模