Minha primeira API em Node.js com Express: CRUD completo passo a passo

Criar a primeira API em Node.js é um marco para qualquer desenvolvedor: é o momento em que você deixa de apenas consumir serviços e passa a construir o seu. Neste tutorial vamos do npm init até uma API REST completa de tarefas, com as quatro operações do CRUD — criar, ler, atualizar e apagar — usando o Express, o framework web mais popular do ecossistema Node.js.

Tudo foi executado de verdade enquanto escrevíamos este guia: os prints mostram exatamente as respostas que a API devolveu. Você pode seguir copiando os comandos e comparando com a sua tela.

O que você vai construir

Uma API de lista de tarefas com estes endpoints:

Método	Rota	O que faz	Status de sucesso
GET	/tarefas	Lista todas as tarefas	200 OK
GET	/tarefas/:id	Busca uma tarefa pelo id	200 OK
POST	/tarefas	Cria uma tarefa	201 Created
PUT	/tarefas/:id	Atualiza uma tarefa	200 OK
DELETE	/tarefas/:id	Remove uma tarefa	204 No Content

Se o conceito de API ainda está nebuloso, leia antes Como funciona uma API? Entenda na prática. Ele explica requisição, resposta e métodos HTTP com exemplos do dia a dia.

Pré-requisitos

• Node.js 20 ou superior instalado. Baixe a versão LTS em nodejs.org. No Windows e no macOS o instalador já inclui o npm.
• Um editor de código. Usamos o VS Code nos prints.
• Um terminal. No Windows, o PowerShell ou o terminal do VS Code funcionam bem.
• Noções básicas de JavaScript: variáveis, funções, arrays e objetos.

Passo 1: criando o projeto e instalando o Express

Crie uma pasta para o projeto, inicialize o package.json e instale o Express:

mkdir minha-api
cd minha-api
npm init -y
npm install express

O npm init -y cria o package.json com valores padrão — é o “documento de identidade” do projeto, onde ficam o nome, os scripts e as dependências. O npm install express baixa o framework para a pasta node_modules e o registra como dependência. Não se assuste com os 68 pacotes: são as dependências internas do Express.

Passo 2: o Hello World da API

Crie o arquivo index.js na raiz do projeto com o mínimo necessário para uma API responder:

Linha a linha:

• require('express') importa o framework, e express() cria a aplicação.
• app.get('/', ...) registra uma rota que responde ao método GET no caminho /.
• A função recebe req (a requisição, com URL, cabeçalhos e corpo) e res (a resposta que vamos devolver).
• res.json() envia um objeto JavaScript convertido em JSON e já define o cabeçalho Content-Type: application/json.
• app.listen(3000) coloca o servidor para escutar na porta 3000.

Rode com:

node index.js

Abra http://localhost:3000 no navegador e você verá o JSON com a mensagem. Sua primeira API em Node.js está respondendo.

Passo 3: entendendo o CRUD e os métodos HTTP

Uma API REST organiza as operações em torno de recursos (aqui, “tarefas”) e usa os métodos HTTP para indicar a intenção:

• GET lê dados e nunca deve alterar nada.
• POST cria um recurso novo.
• PUT atualiza um recurso existente (o PATCH é usado para atualizações parciais; aqui simplificamos com PUT).
• DELETE remove um recurso.

Os códigos de status comunicam o resultado: 200 (ok), 201 (criado), 204 (sucesso sem conteúdo), 400 (requisição inválida), 404 (não encontrado) e 500 (erro no servidor). Um cliente bem escrito toma decisões com base nesses códigos, então devolvê-los corretamente é parte essencial de uma boa API.

Passo 4: rotas de leitura (GET)

Substitua o conteúdo do index.js. Vamos usar um array em memória como “banco de dados” para focar no Express — em um projeto real, esses dados viriam de um MySQL, PostgreSQL ou MongoDB:

Destaques:

• app.use(express.json()) é um middleware que lê o corpo das requisições em JSON e o disponibiliza em req.body. Sem ele, o POST e o PUT não funcionariam.
• process.env.PORT || 3000 permite trocar a porta por variável de ambiente, prática que facilita o deploy.
• Em /tarefas/:id, o trecho :id é um parâmetro de rota, lido em req.params.id. Como ele chega como texto, convertemos com Number().
• Se a tarefa não existe, respondemos 404 com uma mensagem de erro clara, em vez de devolver null com status 200.

Reinicie o servidor e abra http://localhost:3000/tarefas no navegador:

Passo 5: rotas de escrita (POST, PUT e DELETE)

Agora adicione, antes do app.listen, as rotas que alteram dados:

Pontos de atenção:

• Validação no POST: se o titulo não vier no corpo, respondemos 400 Bad Request. Nunca confie nos dados recebidos: valide tudo o que chega do cliente.
• 201 Created: ao criar um recurso, o status correto é 201, e devolvemos o objeto criado (com o id gerado), para o cliente saber o que foi salvo.
• PUT parcial: atualizamos apenas os campos enviados, verificando !== undefined para permitir, por exemplo, concluida: false.
• 204 No Content: no DELETE bem-sucedido não há nada para devolver, então usamos res.status(204).send().

Passo 6: testando a API com cURL

O navegador só faz requisições GET pela barra de endereço. Para testar POST, PUT e DELETE, usamos o cURL, que já vem instalado no Linux, no macOS e no Windows 10/11:

Repare que testamos também os caminhos de erro: buscar uma tarefa inexistente devolveu 404 e criar uma tarefa sem título devolveu 400. Testar só o “caminho feliz” é um dos erros mais comuns de quem está começando. No tutorial Como testar APIs com cURL e Postman você aprende a ler cabeçalhos, medir tempo de resposta e organizar os testes em coleções.

Dica para usuários do Windows: no PowerShell, as aspas simples dentro do JSON podem causar problemas. Use curl.exe em vez de curl e escape as aspas duplas, ou rode os testes pelo Git Bash.

Passo 7: recarregamento automático com node –watch

Reiniciar o servidor a cada alteração cansa. Desde a versão 18.11, o Node.js tem o modo --watch, que reinicia a aplicação sempre que um arquivo muda — sem instalar o nodemon. Adicione um script no package.json:

"scripts": {
  "start": "node index.js",
  "dev": "node --watch index.js"
}

Use npm run dev durante o desenvolvimento e npm start em produção.

Erros comuns na primeira API em Node.js

Error: listen EADDRINUSE: address already in use :::3000 — outro processo já usa a porta 3000 (muitas vezes, uma instância antiga da própria API). Feche o terminal anterior ou rode em outra porta: PORT=3001 node index.js.

req.body chega undefined — faltou o app.use(express.json()) ou o cliente não enviou o cabeçalho Content-Type: application/json.

Cannot GET /rota — a rota não existe ou você usou o método errado (por exemplo, fez GET em uma rota que só aceita POST).

Cannot find module 'express' — você rodou o projeto sem instalar as dependências. Execute npm install na pasta do projeto.

Dados somem ao reiniciar — esperado neste tutorial: o array vive na memória. Para persistir, conecte um banco de dados.

Como evoluir a sua API

1. Banco de dados: troque o array por MySQL/PostgreSQL (com Prisma ou Knex) ou MongoDB (com Mongoose).
2. Organização: separe rotas, controllers e serviços em arquivos diferentes com o express.Router().
3. Segurança: adicione autenticação por token, limite de requisições e validação com bibliotecas como Zod. Nosso artigo sobre rate limiting em APIs mostra como proteger endpoints.
4. Configuração: leve portas, URLs e tokens para variáveis de ambiente — veja Variáveis de ambiente e arquivo .env.
5. Docker: empacote a API em uma imagem, como mostramos em Docker para iniciantes.
6. Integrações: sua API pode consumir outras. Nos tutoriais Consultar CEP com JavaScript e Enviar WhatsApp com Node.js usamos a SDK da APIBrasil dentro de projetos Node.

Para um panorama mais amplo sobre arquitetura e boas práticas, leia também Como desenvolver APIs com Node.js.

Perguntas frequentes

Express ainda é uma boa escolha para APIs em Node.js?

Sim. O Express é maduro, tem a maior comunidade e a versão 5 trouxe melhorias como o tratamento nativo de erros em funções assíncronas. Alternativas como Fastify, NestJS e Hono também são ótimas, mas o Express continua sendo o melhor ponto de partida para aprender.

Qual a diferença entre PUT e PATCH?

Pela especificação, o PUT substitui o recurso inteiro e o PATCH altera apenas os campos enviados. Muitas APIs usam PUT de forma parcial, como fizemos aqui por simplicidade; em uma API pública, siga a semântica correta e documente o comportamento.

Posso usar import em vez de require?

Pode. Adicione "type": "module" no package.json e troque para import express from 'express'. Ambos os formatos funcionam; o importante é ser consistente no projeto.

Como publicar minha API na internet?

Você pode usar uma VPS com Nginx e PM2, serviços como Render, Railway ou Fly.io, ou empacotar em Docker e subir em qualquer provedor de nuvem. Lembre-se de configurar HTTPS e variáveis de ambiente.

Conclusão

Você construiu sua primeira API em Node.js: criou o projeto com npm, instalou o Express, implementou o CRUD completo com status HTTP corretos e validação, testou com o navegador e com o cURL, e configurou o recarregamento automático. Essa base é a mesma de APIs usadas em produção — o que muda é a camada de dados, a organização do código e a segurança.

Próximo tutorial recomendado: Como testar APIs com cURL e Postman. E, quando quiser adicionar recursos como consulta de CEP, CNPJ, SMS ou WhatsApp à sua aplicação, conheça a APIBrasil.