API REST Express: tutorial completo para criar sua primeira API

Criar uma API REST com Express é o passo inicial para construir o backend de aplicações web modernas. Com Node.js e Express, você expõe endpoints que permitem a comunicação entre cliente e servidor de forma padronizada. Este tutorial cobre cada etapa, da instalação ao teste, com dicas para evitar os erros mais comuns que travam iniciantes.

Pré-requisitos: Node.js instalado (versão 14 ou superior), um editor de código (VS Code, Sublime) e familiaridade básica com JavaScript.

Passo 1: Inicializar o projeto

Crie uma pasta para o projeto e, no terminal, execute npm init -y. O arquivo package.json gerado contém as configurações iniciais. Dica: edite a chave "main" para "index.js", muitos iniciantes esquecem e o Node procura por server.js.

Passo 2: Instalar o Express

No terminal, rode npm install express. Isso adiciona o Express e suas dependências ao node_modules. Erro comum: pular o npm init e instalar o Express direto, sem o package.json, o Node não reconhece o módulo.

Passo 3: Criar o servidor básico

Crie um arquivo index.js na raiz. Adicione o código:

const express = require('express'); const app = express(); const port = 3000;

app.listen(port, () => { console.log(Servidor rodando em http://localhost:${port}); });

Execute node index.js e veja a mensagem no terminal. Ressalva: se a porta 3000 estiver ocupada, troque para 3001 ou defina uma variável de ambiente PORT.

Passo 4: Configurar rotas REST

Adicione antes do app.listen:

app.get('/', (req, res) => { res.send('API REST funcionando!'); });

Para uma rota que retorna JSON (padrão REST), use res.json():

app.get('/api/usuarios', (req, res) => { res.json([{ id: 1, nome: 'João' }, { id: 2, nome: 'Maria' }]); });

Dica: sempre retorne JSON em APIs REST, nunca HTML. Isso garante que qualquer cliente (web, mobile, IoT) consuma os dados.

Passo 5: Habilitar parsing de requisições POST/PUT

Para receber dados JSON no corpo da requisição, adicione o middleware:

app.use(express.json());

Coloque essa linha antes das rotas. Erro comum: esquecer esse middleware, req.body fica undefined e a API quebra silenciosamente.

Passo 6: Criar rotas POST, PUT e DELETE

Exemplo de rota POST:

app.post('/api/usuarios', (req, res) => { const { nome } = req.body; res.status(201).json({ id: 3, nome }); });

O código 201 indica "criado com sucesso". Para PUT (atualizar) e DELETE (remover), use app.put() e app.delete(), retornando 200 ou 204.

Passo 7: Testar a API

Use o Postman, Insomnia ou curl. Exemplo com curl:

curl http://localhost:3000/api/usuarios curl -X POST -H "Content-Type: application/json" -d '{"nome":"Ana"}' http://localhost:3000/api/usuarios

Ressalva: se o servidor não responder, verifique se o terminal mostra Servidor rodando... e se a porta não está bloqueada por firewall local.

Checklist do que foi feito

• [ ] Projeto inicializado com npm init
• [ ] Express instalado como dependência
• [ ] Servidor rodando na porta 3000
• [ ] Rota GET que retorna JSON
• [ ] Middleware express.json() configurado
• [ ] Rotas POST, PUT e DELETE criadas
• [ ] Testes realizados com Postman ou curl

Perguntas frequentes sobre API REST Express

Qual a diferença entre API REST e API RESTful?

REST é o conjunto de princípios (stateless, recursos identificados por URL, uso de verbos HTTP). RESTful é uma API que segue esses princípios. Na prática, os termos são usados como sinônimos, mas RESTful indica conformidade total.

Preciso usar banco de dados para criar uma API REST?

Não. Você pode começar com dados mockados (arrays ou objetos em memória), como fizemos neste tutorial. Para produção, integre com MongoDB, PostgreSQL ou outro banco.

Como lidar com erros em rotas Express?

Use middlewares de erro. Crie uma função que receba (err, req, res, next) e retorne res.status(500).json({ erro: err.message }). Coloque-a depois de todas as rotas.

O que é CORS e preciso configurar?

CORS (Cross-Origin Resource Sharing) controla quais domínios podem acessar sua API. Se o frontend estiver em outro domínio, instale npm install cors e use app.use(cors()).

Como organizar rotas em arquivos separados?

Crie uma pasta routes/, defina as rotas com express.Router() e importe no index.js com app.use('/api', router). Isso mantém o código modular.

Qual a diferença entre res.send() e res.json()?

res.send() envia qualquer tipo (string, buffer, objeto). res.json() converte automaticamente para JSON e define o header Content-Type: application/json. Prefira res.json() em APIs REST para consistência.