REST API: como evitar erros comuns e aplicar boas práticas

Estrutura e nomenclatura de endpoints

// Exemplo ruim (endpoint com verbo e nomenclatura não padronizada):
app.get('/getAllUsers', ...);

// Bom exemplo (endpoint descritivo, substantivo plural):
app.get('/users', (req, res) => {
  const users = [ 
    { id: 1, nome: 'Diego' }, 
    { id: 2, nome: 'Mayk' }
  ];
  res.json(users);
});

• Use nomes de recursos (substantivos) em vez de ações.

• Prefira plural para coleções (ex: /users para coleção de usuários).

• Mantenha URLs legíveis e consistentes (minúsculas, separadores padronizados).

• Estruture URLs refletindo relações de dados (endpoints aninhados quando necessário, mas sem exagero de profundidade).

Com essas práticas, você terá endpoints limpos, organizados e fáceis de consumir, e evitará a confusão que a falta de padrão causa.

Uso correto de métodos HTTP

import express from 'express';
const app = express();
app.use(express.json());

// GET: obter lista de usuários
app.get('/users', (req, res) => {
  // ... código para pegar usuários
  res.status(200).json([...]);
});

// POST: criar novo usuário
app.post('/users', (req, res) => {
  const novoUsuario = req.body;
  // ... código para salvar novoUsuario
  res.status(201).json({ message: 'Usuário criado com sucesso!', user: novoUsuario });
});

// DELETE: remover usuário por ID
app.delete('/users/:id', (req, res) => {
  const userId = req.params.id;
  // ... código para deletar usuário de id = userId
  res.status(204).send(); // 204 No Content (remoção sem retornar conteúdo)
});

Lembre-se: ao consumir APIs REST, você também espera que elas sigam essas convenções. Portanto, forneça essa consistência para os consumidores da sua API. Cada método no lugar certo deixa a integração mais fácil e reduz erros.

Códigos de Status HTTP

app.get('/users/:id', (req, res) => {
  const { id } = req.params;
  const user = users.find(u => u.id === Number(id));
  if (!user) {
    return res.status(404).json({ erro: 'Usuário não encontrado' });
  }
  res.status(200).json(user);
});

Em resumo, use os HTTP status codes a seu favor para comunicar sucesso ou falha. Essa é uma das boas práticas REST API fundamentais para um design de API profissional.

Padrão nos payloads (request/response)

// Definição de interface para User
interface User {
  id: number;
  nome: string;
  email: string;
  idade?: number;
}

// Exemplo de função Express que retorna um usuário
app.get('/users/:id', (req, res) => {
  const user: User | undefined = /* lógica para obter usuário */;
  if (!user) {
    return res.status(404).json({ erro: 'Usuário não encontrado' });
  }
  res.status(200).json(user);
});

Mantendo os payloads padronizados e a API stateless, você proporciona uma experiência muito melhor para quem consome a API (eles podem reutilizar código de parsing de resposta, tratar erros de forma genérica, etc.) e torna a manutenção do servidor mais tranquila.

Versionamento de APIs

// V1
app.get('/api/v1/users', (req, res) => {
  res.json([ { id: 1, nome: 'Diego', email: 'diego@example.com' } ]);
});

// V2
app.get('/api/v2/users', (req, res) => {
  res.json([ { id: 1, nomeCompleto: 'Diego Fernandes', email: 'diego@example.com', idade: 25 } ]);
});

Versionar a REST API é crucial para manter uma evolução saudável. Isso demonstra maturidade no projeto e respeito pelos consumidores. Grandes empresas (Google, Meta etc.) versionam suas APIs; Alunos da Rocketseat não fazem diferente: fornecem uma API que evolui sem deixar ninguém para trás!

Segurança em APIs REST (HTTPS, JWT e validações)

import jwt from 'jsonwebtoken';

const authMiddleware = (req, res, next) => {
  const authHeader = req.headers['authorization'];
  if (!authHeader) {
    return res.status(401).json({ erro: 'Token não fornecido' });
  }
  const token = authHeader.split(' ')[1];
  try {
    const payload = jwt.verify(token, process.env.JWT_SECRET);
    req.user = payload; // payload contém info do usuário (ex: id, role)
    next(); // usuário autenticado, prossegue
  } catch (e) {
    return res.status(403).json({ erro: 'Token inválido ou expirado' });
  }
};

// Uso do middleware em uma rota protegida:
app.get('/api/v1/mentoria', authMiddleware, (req, res) => {
  // Se chegou aqui, req.user está definido
  res.json({ message: `Bem-vindo à área de mentoria, ${req.user.name}!` });
});

import { z } from 'zod';

const userSchema = z.object({
  nome: z.string().min(1),
  email: z.string().email(),
  idade: z.number().int().nonnegative().optional()
});

app.post('/api/v1/users', (req, res) => {
  const parseResult = userSchema.safeParse(req.body);
  if (!parseResult.success) {
    return res.status(400).json({ erro: 'Dados inválidos', detalhes: parseResult.error.errors });
  }
  // se válido, prossegue para criar usuário
  const userData = parseResult.data;
  // ... salvar userData
  res.status(201).json({ message: 'Usuário criado', user: userData });
});

• Sempre use HTTPS em produção.

• Autentique as requisições com tokens (ex: JWT) e verifique permissões quando aplicável.

• Valide e sanitize todos os dados vindos do cliente.

• Mantenha sua API stateless no que tange à autenticação (não use sessão de servidor, use token).

• Utilize ferramentas auxiliares: bibliotecas de segurança (Helmet no Express para cabecalhos seguros, rate limit para evitar abuso de requests, CORS configurado corretamente para evitar acessos indevidos de origens não autorizadas).

Seguindo essas práticas, você protege os dados dos usuários e constrói uma API confiável. Lembre-se: uma API insegura pode comprometer todo o sistema, então segurança não é opcional.

Performance e escalabilidade (paginação e otimização de consultas)

• Paginação tradicional: use parâmetros como ?page=1&limit=50. A requisição GET /posts?page=2&limit=50 retornaria os posts de 51 a 100, por exemplo. No response, você pode incluir cabeçalhos ou campos indicando quantos resultados totais existem, qual a próxima página, etc. Exemplo de resposta com meta:

{
  "data": [ /* array de até 50 posts */ ],
  "page": 2,
  "per_page": 50,
  "total": 247,
  "total_pages": 5
}

Assim, o cliente pode paginar conforme necessário.

• Limite padrão: mesmo que não implemente toda uma paginação com página e etc., tenha pelo menos um limit padrão. Por exemplo, GET /posts retorna por padrão 100 itens no máximo, e pode aceitar um query param ?limit=200 até um teto estabelecido. Nunca retorne 10 mil registros de uma vez sem necessidade.

• Scroll ou cursores: em casos de alta escala, você pode usar paginação baseada em cursor (ex: ?after=id_ultimo_recebido), muito comum em APIs de redes sociais, para eficiência. Mas para desenvolvedores(as) iniciantes, entender a paginação simples já é um ótimo começo.

• Se for um banco de dados SQL, use LIMIT e OFFSET nas queries.

• Em MongoDB, use .limit(n).skip(n*page) ou preferencialmente cursos com _id > last_id.

• ORMs geralmente têm métodos de paginação (ex: .findMany({ skip: 50, take: 50 }) no Prisma, ou .limit().offset() no Sequelize/TypeORM).

app.get('/api/v1/posts', async (req, res) => {
  const page = parseInt(req.query.page as string) || 1;
  const limit = parseInt(req.query.limit as string) || 50;
  const offset = (page - 1) * limit;
  const [results, total] = await db.Post.findAndCountAll({ limit, offset }); // exemplo ORM
  res.json({
    data: results,
    page,
    per_page: limit,
    total,
    total_pages: Math.ceil(total/limit)
  });
});

• Use índices adequadamente: identifique quais campos são mais filtrados (por exemplo, email de usuário, nome de produto) e certifique-se de indexá-los no banco de dados. Índices aceleram muito buscas. Em ORMs ou query builders, às vezes você precisa definir isso no esquema. Em SQL puro, crie índices via migrations.

• Evite N+1 queries: Se você precisa carregar dados relacionados, busque maneiras de fazer isso em uma consulta otimizada. ORMs normalmente oferecem algo como eager loading (ex: .include no Prisma, .populate no Mongoose, JOIN manual em SQL). Exemplo: ao buscar usuários com seus pedidos, faça uma consulta que já traga os pedidos de cada usuário, em vez de uma pra cada.

• Cache de consultas frequentes: se certos endpoints fazem consultas pesadas mas com resultados que repetem (ex: dados que mudam pouco, ou listas públicas), considere implementar um cache. Pode ser na memória (Node cache, Redis) ou nível de banco (materialized views, etc.). Em Node, integrar com Redis para cache de algumas respostas pode aliviar o banco de dados.

• CDN e cache HTTP: para dados públicos que não mudam a cada segundo, use cabeçalhos HTTP de cache (Cache-Control) para permitir que clientes e intermediários (CDNs) cacheiem as respostas. Ex: uma lista de produtos que muda diariamente poderia ter Cache-Control: public, max-age=300 (5 minutos). Isso reduz chamadas repetidas.

• Compressão de resposta: ative gzip/deflate. O Express tem o middleware compression() que comprime as respostas, economizando banda e tempo de transferência, especialmente para payloads JSON grandes.

• Evite processamento desnecessário no servidor: por exemplo, não gere dados que o cliente não usa. Se a API tem opção de filtro de campos (fields), pode implementar para retornar só o necessário. Mas principalmente, não faça loops ou transformações custosas se puder delegar ao banco de dados ou a bibliotecas eficientes.

• Mantenha também um olho em monitoramento e logging. Uma API escalável precisa ser observável: use logs (lib como morgan para logs HTTP, ou Winston para logs gerais) e monitore métricas (tempo de resposta, uso de CPU/RAM). Assim você antecipa gargalos.

• Rate limiting: Para escalabilidade e segurança, implemente limites de requisição por IP/usuário para evitar abuso (ataques de DDoS ou apenas uso excessivo). Libs como express-rate-limit podem ajudar, ou no próprio proxy (NGINX etc.).

• Implemente paginação ou limites em endpoints de listagem.

• Otimize consultas de banco (índices, evitar N+1, busca eficiente).

• Use cache onde fizer sentido e comprimir respostas.

• Mantenha a API stateless para escalar horizontalmente facilmente.

• Considere balanceamento de carga e uso eficiente de recursos (multi-thread/process, etc.).

Com essas práticas, sua API estará pronta para crescer. Seja 100 ou 1 milhão de usuários, uma base bem pensada permitirá que a experiência continue rápida e fluida. Lembre-se: a experiência do usuário final muitas vezes depende da performance da API – ninguém gosta de esperar ou de ver um app travar por um excesso de dados. Então, assim como ensinamos na Rocketseat, pense em desempenho desde o início!

Conclusão