Construtor de Endpoints de API

Construa endpoints de API REST completos e prontos para produção com validação adequada, tratamento de erros, autenticação e documentação.

Quando Usar Esta Habilidade

• O usuário pede para "criar um endpoint de API" ou "construir uma API REST"
• Construindo novos recursos de backend
• Adicionando endpoints a APIs existentes
• O usuário menciona "API", "endpoint", "rota" ou "REST"
• Criando operações CRUD

O Que Você Construirá

Para cada endpoint que você criar:

• Manipulador de rota com o método HTTP apropriado
• Validação de entrada (corpo da requisição, parâmetros, query)
• Verificações de autenticação/autorização
• Lógica de negócios
• Tratamento de erros
• Formatação de resposta
• Documentação da API
• Testes (se solicitado)

Estrutura do Endpoint

1. Definição da Rota

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

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

2. Validação de Entrada

Sempre valide antes de processar:

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. Implementação do Manipulador

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' });
  }
};

Melhores Práticas

Códigos de Status HTTP

• 200 - Sucesso (GET, PUT, PATCH)
• 201 - Criado (POST)
• 204 - Sem Conteúdo (DELETE)
• 400 - Requisição Inválida (falha na validação)
• 401 - Não Autorizado (não autenticado)
• 403 - Proibido (não autorizado)
• 404 - Não Encontrado
• 409 - Conflito (duplicado)
• 500 - Erro Interno do Servidor

Formato da Resposta

Estrutura consistente:

// Success
{
  "success": true,
  "data": { ... }
}

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

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

Checklist de Segurança

• Autenticação necessária para rotas protegidas
• Verificações de autorização (usuário é dono do recurso)
• Validação de entrada em todos os campos
• Prevenção de injeção de SQL (use consultas parametrizadas)
• Limitação de taxa em endpoints públicos
• Nenhum dado sensível em respostas (senhas, tokens)
• CORS configurado corretamente
• Limites de tamanho de requisição definidos

Tratamento de Erros

// 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 });
});

Padrões Comuns

Operações CRUD

// 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

Paginação

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,

…