Como Criar API REST com Node.js: Tutorial Completo 2026
Construa APIs REST profissionais com Node.js e Express. Do setup inicial ao deploy, com autenticação JWT, validação e boas práticas de produção.
Por que isso é importante
Como Criar API REST com Node.js: Tutorial Completo 2026. Construa APIs REST profissionais com Node.js e Express. Do setup inicial ao deploy, com autenticação JWT, validação e boas práticas de produção.
O que é uma API REST
REST (Representational State Transfer) é um padrão de arquitetura para comunicação entre sistemas. Uma API REST usa métodos HTTP (GET, POST, PUT, DELETE) para manipular recursos identificados por URLs.
Node.js se tornou a escolha dominante para APIs REST por três motivos: velocidade do V8 engine, modelo non-blocking I/O que suporta milhares de conexões simultâneas, e o ecossistema npm com mais de 2 milhões de pacotes.
Node.js vs alternativas para APIs
Node.js + Express: Setup em 5 minutos, npm gigante, JavaScript end-to-end
Python + Django: Mais lento para I/O intensivo, melhor para data science
Go: Mais rápido em CPU-bound, curva de aprendizado maior
Java + Spring: Robusto para enterprise, mais verboso
Setup do Projeto
Vamos construir uma API REST completa para gerenciar usuários. O projeto usa Node.js 20+, Express como framework HTTP, e segue a estrutura de pastas que empresas reais utilizam.
npm init -y para criar o package.json. Depois instale as dependências: npm install express cors dotenvsrc/routes, src/controllers, src/middleware e src/models. Essa separação facilita testes e manutenção.src/server.js com Express, registre middleware de CORS e JSON parsing, e configure a porta via variável de ambiente..env com PORT, DATABASE_URL e JWT_SECRET. Nunca commite secrets no repositório.Rotas e Controllers
O padrão MVC separa responsabilidades. Rotas definem endpoints, controllers processam lógica de negócio, e models interagem com o banco de dados. Essa separação permite que equipes trabalhem em paralelo sem conflitos.
Estrutura de Rotas RESTful
Uma API REST bem desenhada segue convenções claras. Para o recurso "usuários": GET /users lista todos, GET /users/:id busca um específico, POST /users cria novo, PUT /users/:id atualiza, e DELETE /users/:id remove.
Boas práticas de rotas
Use substantivos no plural: /users, /products, /orders
Versionamento: Prefixe com /api/v1/ para manter compatibilidade
Status codes corretos: 200 (OK), 201 (Created), 400 (Bad Request), 404 (Not Found), 500 (Server Error)
Paginação: Use query params como ?page=1&limit=20
Middleware: O Poder do Express
Middleware são funções que interceptam requests antes de chegarem ao controller. Eles processam autenticação, validação, logging e tratamento de erros de forma modular e reutilizável.
req.user. Se inválido, retorna 401.express-rate-limit com limites como 100 requests por 15 minutos.Autenticação JWT
JSON Web Tokens (JWT) são o padrão para autenticação stateless em APIs REST. O servidor gera um token assinado no login, e o cliente envia esse token em cada request subsequente.
Fluxo de Autenticação
Authorization: Bearer <token> em cada request. Middleware verifica assinatura e expiração.Segurança JWT
Nunca armazene JWT no localStorage (vulnerável a XSS). Use httpOnly cookies para refresh tokens. Mantenha access tokens curtos (15min). Implemente blacklist para logout forçado. Use algoritmo RS256 em produção para separar chaves de assinatura e verificação.
Validação de Dados com Zod
Validar dados de entrada é a primeira linha de defesa contra bugs e ataques. Zod é a biblioteca mais popular para validação em TypeScript/JavaScript, com inferência de tipos automática.
Defina schemas para cada endpoint: createUserSchema valida email (formato válido), password (mínimo 8 caracteres, 1 maiúscula, 1 número) e name (mínimo 2 caracteres). O middleware de validação aplica o schema automaticamente antes do controller processar a request.
Vantagens do Zod sobre Joi
TypeScript-first: Inferência automática de tipos a partir do schema
Bundle menor: 13kb vs 79kb do Joi
Zero dependências: Nenhum pacote adicional necessário
Mensagens customizáveis: Erros em português se necessário
Banco de Dados: MongoDB vs PostgreSQL
A escolha do banco impacta performance, escalabilidade e produtividade. Para APIs REST, ambos são escolhas sólidas, mas com trade-offs distintos.
MongoDB + Mongoose
Banco NoSQL com schema flexível
Prós
- Schema flexível para prototipação rápida
- Escalabilidade horizontal nativa
- JSON nativo (sem ORM pesado)
- Atlas gratuito com 512MB
Contras
- Sem transações ACID em múltiplas collections
- Queries complexas menos eficientes
- Dados duplicados sem normalização
PostgreSQL + Prisma
Banco relacional com ORM moderno
Prós
- ACID completo para dados financeiros
- Prisma gera tipos TypeScript automáticos
- Queries complexas com JOINs eficientes
- Supabase/Neon gratuito com 500MB
Contras
- Schema rígido exige migrations
- Escalabilidade horizontal mais complexa
- Setup inicial mais verboso
Tratamento de Erros Profissional
APIs profissionais nunca expõem stack traces ao cliente. Implemente um error handler centralizado que converte exceções em respostas JSON padronizadas com status codes corretos.
{ success: false, error: { message, code } }. Inclua campo details apenas em development.Testes Automatizados
APIs sem testes quebram em produção. O stack recomendado: Jest para unit tests, Supertest para integration tests dos endpoints, e um banco de testes isolado.
Teste cada rota com cenários de sucesso e falha. Para POST /users: teste criação válida (201), email duplicado (409), dados inválidos (400) e falha no banco (500). Integration tests verificam o fluxo completo: request HTTP, processamento, resposta e estado do banco.
Cobertura mínima recomendada
Controllers: 100% das rotas com happy path e error paths
Middleware: Autenticação, validação e error handler
Models: Validações de schema e queries customizadas
Meta: Acima de 80% de cobertura total
Deploy Gratuito
Você não precisa pagar servidor para colocar sua API no ar. Plataformas modernas oferecem tiers gratuitos generosos para projetos de estudo e MVPs.
railway up. Tier gratuito com 500 horas/mês, banco PostgreSQL incluso. Ideal para APIs completas.flyctl launch. 3 máquinas gratuitas, ideal para APIs que precisam de baixa latência em múltiplas regiões.Checklist de Produção
Antes de ir para produção
Próximos Passos
Você agora tem a base para construir APIs REST profissionais com Node.js. O caminho natural de evolução: adicione WebSockets para real-time, implemente caching com Redis, explore microserviços com Docker, e escale com Kubernetes.
Para ir além, combine essa API com um frontend React ou Next.js e construa aplicações full stack completas. O ecossistema JavaScript permite usar a mesma linguagem do banco ao browser.