Como criar uma API com Node.js do zero

Criar uma API com Node.js é um dos primeiros passos para quem quer aprender back-end com JavaScript. Depois que você entende HTML, CSS e JavaScript no navegador, o próximo nível é aprender como o front-end conversa com o servidor, como os dados são enviados, como uma rota responde e como uma aplicação pode entregar informações em formato JSON.

Node.js é um ambiente de execução JavaScript que roda fora do navegador, usando o motor V8. Isso permite usar JavaScript para criar servidores, APIs, ferramentas de linha de comando e vários tipos de aplicações. Para facilitar a criação de rotas e servidores web, vamos usar o Express, que é um framework leve e flexível baseado em rotas e middlewares.

Este artigo segue uma proposta prática: você vai criar uma API simples com Node.js e Express, entender o que cada parte faz e acompanhar exemplos de código funcionais para estudar e reproduzir no seu editor.

API significa Interface de Programação de Aplicações. De forma simples, uma API permite que sistemas diferentes conversem entre si.

Imagine um aplicativo de clima. A tela que o usuário vê é o front-end. Mas os dados de temperatura, cidade e previsão geralmente vêm de algum servidor. Esse servidor disponibiliza uma API. O front-end faz uma requisição, a API processa o pedido e devolve uma resposta, normalmente em JSON.

Um exemplo de resposta JSON seria:

{
  "cidade": "São Paulo",
  "temperatura": 24,
  "descricao": "Parcialmente nublado"
}

Esse formato é fácil de ler, fácil de enviar pela internet e muito usado em aplicações modernas.

Vamos criar uma API simples de tarefas. Ela terá rotas para listar tarefas, buscar uma tarefa por ID, criar uma nova tarefa, atualizar uma tarefa e remover uma tarefa.

A API será simples, mas vai mostrar a base de um CRUD, que significa:

• Create: criar dados
• Read: ler dados
• Update: atualizar dados
• Delete: apagar dados

Essas operações aparecem em muitas aplicações do dia a dia, como agenda, lista de tarefas, painel administrativo, loja online, blog, sistema de usuários e aplicativo financeiro.

Para acompanhar este tutorial, você precisa ter o Node.js instalado no computador. Também é importante ter noções básicas de JavaScript, como variáveis, arrays, objetos, funções e condições.

Neste artigo, vamos usar:

• Node.js
• JavaScript
• Express
• JSON
• Terminal
• Editor de código, como VS Code

Como tecnologia muda rápido, sempre vale conferir a versão instalada no seu computador antes de iniciar o projeto. Isso ajuda a evitar erros de comando e problemas com dependências.

No terminal, rode:

node -v

Depois:

npm -v

Se os comandos retornarem versões, o Node e o npm estão instalados corretamente.

Primeiro, crie uma pasta para o projeto. Você pode chamar de api-node-tarefas.

No terminal:

mkdir api-node-tarefas
cd api-node-tarefas

Agora inicialize o projeto Node:

npm init -y

Esse comando cria o arquivo package.json, que guarda informações do projeto, scripts e dependências instaladas.

Depois, instale o Express:

npm install express

O Express será usado para criar o servidor, configurar rotas e responder requisições HTTP.

Por padrão, muitos projetos Node podem usar require, mas neste tutorial vamos usar import e export, que deixam o código mais moderno e organizado.

Abra o arquivo package.json e adicione "type": "module". O arquivo pode ficar assim:

{
  "name": "api-node-tarefas",
  "version": "1.0.0",
  "description": "API simples de tarefas com Node.js e Express",
  "main": "server.js",
  "type": "module",
  "scripts": {
    "dev": "node server.js"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "express": "^5.0.0"
  }
}

A versão exata do Express pode variar dependendo do momento em que você instalar. O mais importante é manter o projeto funcionando e testar cada rota antes de publicar o artigo.

Agora crie um arquivo chamado server.js na raiz do projeto.

Dentro dele, coloque:

import express from "express";

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

app.use(express.json());

app.get("/", (req, res) => {
  res.json({
    mensagem: "API de tarefas rodando com Node.js e Express"
  });
});

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

Esse é o primeiro servidor da nossa API.

• A linha import express from "express" importa o Express.
• A linha const app = express() cria a aplicação.
• A linha app.use(express.json()) permite que a API receba dados em JSON.
• A rota app.get("/") responde quando alguém acessa a raiz da API.
• O app.listen inicia o servidor na porta 3000.

Para rodar o projeto, use:

npm run dev

Depois acesse no navegador:

http://localhost:3000

A resposta esperada será:

{
  "mensagem": "API de tarefas rodando com Node.js e Express"
}

Uma API normalmente usa métodos HTTP para indicar o tipo de ação que será feita. A MDN explica que métodos HTTP indicam o propósito da requisição, ou seja, o que se espera que aconteça quando o cliente envia um pedido ao servidor.

Os métodos mais comuns em uma API REST são:

• GET: buscar dados
• POST: criar dados
• PUT: atualizar dados completos
• PATCH: atualizar parte dos dados
• DELETE: remover dados

Neste tutorial, vamos usar GET, POST, PUT e DELETE.

Antes de usar banco de dados, vamos guardar as tarefas em um array. Isso deixa o aprendizado mais simples.

Atualize o arquivo server.js:

import express from "express";

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

app.use(express.json());

let tarefas = [
  {
    id: 1,
    titulo: "Estudar lógica de programação",
    concluida: false
  },
  {
    id: 2,
    titulo: "Criar primeira API com Node.js",
    concluida: false
  }
];

app.get("/", (req, res) => {
  res.json({
    mensagem: "API de tarefas rodando com Node.js e Express"
  });
});

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

Aqui criamos um array chamado tarefas. Cada tarefa tem id, titulo e concluida.

Em um projeto real, esses dados normalmente ficariam em um banco de dados, como PostgreSQL, MySQL, MongoDB ou Supabase. Mas, para aprender a lógica de uma API, usar um array é uma ótima escolha.

Agora vamos criar uma rota GET para listar todas as tarefas.

Adicione este trecho antes do app.listen:

app.get("/tarefas", (req, res) => {
  res.status(200).json(tarefas);
});

O arquivo agora terá uma rota /tarefas.

Quando você acessar:

http://localhost:3000/tarefas

A resposta será:

[
  {
    "id": 1,
    "titulo": "Estudar lógica de programação",
    "concluida": false
  },
  {
    "id": 2,
    "titulo": "Criar primeira API com Node.js",
    "concluida": false
  }
]

O status 200 indica sucesso. Códigos de status HTTP informam se uma requisição foi concluída com sucesso, se houve erro do cliente, erro do servidor ou outro tipo de resposta.

Agora vamos criar uma rota para buscar apenas uma tarefa.

app.get("/tarefas/:id", (req, res) => {
  const id = Number(req.params.id);

  const tarefa = tarefas.find((item) => item.id === id);

  if (!tarefa) {
    return res.status(404).json({
      mensagem: "Tarefa não encontrada"
    });
  }

  res.status(200).json(tarefa);
});

Aqui usamos req.params.id para pegar o ID que vem na URL.

Exemplo:

http://localhost:3000/tarefas/1

A resposta será a tarefa com ID 1. Se o usuário tentar acessar uma tarefa que não existe, a API retorna status 404, indicando que o recurso não foi encontrado.

Agora vamos criar uma rota POST para adicionar novas tarefas.

app.post("/tarefas", (req, res) => {
  const { titulo } = req.body;

  if (!titulo) {
    return res.status(400).json({
      mensagem: "O título da tarefa é obrigatório"
    });
  }

  const novaTarefa = {
    id: tarefas.length + 1,
    titulo,
    concluida: false
  };

  tarefas.push(novaTarefa);

  res.status(201).json({
    mensagem: "Tarefa criada com sucesso",
    tarefa: novaTarefa
  });
});

Essa rota recebe um JSON no corpo da requisição.

Exemplo de envio:

{
  "titulo": "Praticar rotas no Express"
}

Se o título não for enviado, a API retorna status 400, indicando erro na requisição do cliente.

Se a tarefa for criada, retorna status 201, que normalmente é usado quando um recurso foi criado com sucesso.

Agora vamos criar uma rota PUT para atualizar uma tarefa existente.

app.put("/tarefas/:id", (req, res) => {
  const id = Number(req.params.id);
  const { titulo, concluida } = req.body;

  const tarefa = tarefas.find((item) => item.id === id);

  if (!tarefa) {
    return res.status(404).json({
      mensagem: "Tarefa não encontrada"
    });
  }

  if (!titulo) {
    return res.status(400).json({
      mensagem: "O título da tarefa é obrigatório"
    });
  }

  tarefa.titulo = titulo;
  tarefa.concluida = concluida ?? tarefa.concluida;

  res.status(200).json({
    mensagem: "Tarefa atualizada com sucesso",
    tarefa
  });
});

Essa rota permite alterar o título e o status da tarefa.

Exemplo de envio:

{
  "titulo": "Criar API REST com Node e Express",
  "concluida": true
}

O operador ?? mantém o valor antigo caso concluida não seja enviado.

Agora vamos criar a rota DELETE.

app.delete("/tarefas/:id", (req, res) => {
  const id = Number(req.params.id);

  const tarefaExiste = tarefas.some((item) => item.id === id);

  if (!tarefaExiste) {
    return res.status(404).json({
      mensagem: "Tarefa não encontrada"
    });
  }

  tarefas = tarefas.filter((item) => item.id !== id);

  res.status(200).json({
    mensagem: "Tarefa removida com sucesso"
  });
});

Aqui usamos filter para criar uma nova lista sem a tarefa removida.

Exemplo de rota:

DELETE http://localhost:3000/tarefas/2

Se a tarefa existir, ela será removida. Se não existir, a API retornará uma mensagem de erro.

Agora o arquivo server.js completo fica assim:

import express from "express";

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

app.use(express.json());

let tarefas = [
  {
    id: 1,
    titulo: "Estudar lógica de programação",
    concluida: false
  },
  {
    id: 2,
    titulo: "Criar primeira API com Node.js",
    concluida: false
  }
];

app.get("/", (req, res) => {
  res.json({
    mensagem: "API de tarefas rodando com Node.js e Express"
  });
});

app.get("/tarefas", (req, res) => {
  res.status(200).json(tarefas);
});

app.get("/tarefas/:id", (req, res) => {
  const id = Number(req.params.id);

  const tarefa = tarefas.find((item) => item.id === id);

  if (!tarefa) {
    return res.status(404).json({
      mensagem: "Tarefa não encontrada"
    });
  }

  res.status(200).json(tarefa);
});

app.post("/tarefas", (req, res) => {
  const { titulo } = req.body;

  if (!titulo) {
    return res.status(400).json({
      mensagem: "O título da tarefa é obrigatório"
    });
  }

  const novaTarefa = {
    id: tarefas.length + 1,
    titulo,
    concluida: false
  };

  tarefas.push(novaTarefa);

  res.status(201).json({
    mensagem: "Tarefa criada com sucesso",
    tarefa: novaTarefa
  });
});

app.put("/tarefas/:id", (req, res) => {
  const id = Number(req.params.id);
  const { titulo, concluida } = req.body;

  const tarefa = tarefas.find((item) => item.id === id);

  if (!tarefa) {
    return res.status(404).json({
      mensagem: "Tarefa não encontrada"
    });
  }

  if (!titulo) {
    return res.status(400).json({
      mensagem: "O título da tarefa é obrigatório"
    });
  }

  tarefa.titulo = titulo;
  tarefa.concluida = concluida ?? tarefa.concluida;

  res.status(200).json({
    mensagem: "Tarefa atualizada com sucesso",
    tarefa
  });
});

app.delete("/tarefas/:id", (req, res) => {
  const id = Number(req.params.id);

  const tarefaExiste = tarefas.some((item) => item.id === id);

  if (!tarefaExiste) {
    return res.status(404).json({
      mensagem: "Tarefa não encontrada"
    });
  }

  tarefas = tarefas.filter((item) => item.id !== id);

  res.status(200).json({
    mensagem: "Tarefa removida com sucesso"
  });
});

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

Esse código reúne a base da API: servidor inicial, array de tarefas, rota GET, rota POST, rota PUT, rota DELETE e resposta JSON.

Você pode testar a API usando ferramentas como Postman, Insomnia, Thunder Client ou até extensões dentro do VS Code.

Rotas criadas:

GET http://localhost:3000/
GET http://localhost:3000/tarefas
GET http://localhost:3000/tarefas/1
POST http://localhost:3000/tarefas
PUT http://localhost:3000/tarefas/1
DELETE http://localhost:3000/tarefas/1

Para POST e PUT, envie o corpo em JSON.

Exemplo para criar:

{
  "titulo": "Aprender middleware no Express"
}

Exemplo para atualizar:

{
  "titulo": "Aprender middleware e rotas no Express",
  "concluida": true
}

Essa API ainda é simples, mas já ensina a estrutura principal de um back-end com Node.js. Depois, você pode melhorar o projeto adicionando:

• organização por pastas
• controllers
• services
• banco de dados
• variáveis de ambiente
• autenticação
• validação mais completa
• tratamento global de erros
• documentação da API

Uma estrutura um pouco mais organizada poderia ser:

api-node-tarefas/
├── src/
│   ├── controllers/
│   │   └── tarefasController.js
│   ├── routes/
│   │   └── tarefasRoutes.js
│   └── server.js
├── package.json

Essa separação ajuda quando o projeto começa a crescer. Em vez de deixar tudo no server.js, você divide responsabilidades.

Um erro comum é esquecer app.use(express.json()). Sem isso, o Express pode não interpretar corretamente o corpo da requisição em JSON.

Outro erro é não validar os dados recebidos. Se a API espera um título, mas o usuário envia um corpo vazio, o servidor precisa responder com uma mensagem clara.

Também é comum confundir req.params, req.body e req.query.

• req.params pega valores da URL, como /tarefas/1.
• req.body pega dados enviados no corpo da requisição.
• req.query pega filtros na URL, como /tarefas?concluida=true.

Outro cuidado importante é não publicar código que não funciona. Em artigos de programação, o código precisa ser testado, os comandos precisam fazer sentido e o leitor precisa conseguir reproduzir o resultado. Esse é um ponto essencial para passar confiança em conteúdos de tecnologia.

Criar uma API com Node.js é uma excelente forma de entrar no desenvolvimento back-end com JavaScript. Com poucas linhas de código, você consegue criar um servidor, definir rotas, receber dados em JSON, responder requisições e montar uma base parecida com aplicações reais.

Neste tutorial, você criou uma API de tarefas com Express, usando rotas GET, POST, PUT e DELETE. Também viu como trabalhar com parâmetros, corpo da requisição, status HTTP e validações simples.

O próximo passo é organizar melhor o projeto, conectar um banco de dados e criar uma API mais próxima de uma aplicação real. Mas antes disso, vale praticar bastante esse modelo simples. Entender bem a base evita confusão quando você avançar para autenticação, banco de dados, deploy e arquitetura de projetos maiores.