Como Construir uma API REST Mínima em Node.js

Você precisa de um backend rápido para o seu projeto frontend. Talvez seja um protótipo, desenvolvimento local ou um serviço de produção simples. Configurar uma API REST em Node.js não deveria exigir uma semana de configuração.

Este guia orienta você na construção de uma API REST mínima usando Node.js moderno e Express 5. Você terá parsing de JSON, tratamento adequado de erros e uma estrutura limpa—tudo em ~80 linhas de código.

Pré-requisitos

Antes de começar, certifique-se de ter:

• Node.js 24 LTS ou mais recente instalado (pode ser baixado do site oficial do Node.js)
• Um editor de código
• Conhecimento básico de JavaScript

Configuração do Projeto

Crie um novo diretório e inicialize seu projeto:

mkdir minimal-api
cd minimal-api
npm init -y

Instale o Express 5:

npm install express

Abra o package.json e adicione "type": "module" para habilitar imports ESM. Seu arquivo deve incluir:

{
  "type": "module",
  "scripts": {
    "start": "node server.js"
  }
}

Construindo Sua API com Express 5

Crie o arquivo server.js com o seguinte código:

import express from 'express'

const app = express()
const PORT = process.env.PORT || 3000

// Built-in JSON parsing middleware
app.use(express.json())

// In-memory data store
let items = [
  { id: 1, name: 'First item' },
  { id: 2, name: 'Second item' }
]

let nextId = 3

// GET all items
app.get('/api/items', (req, res) => {
  res.json({ data: items })
})

// GET single item
app.get('/api/items/:id', (req, res) => {
  const item = items.find(i => i.id === parseInt(req.params.id))
  if (!item) {
    return res.status(404).json({ error: 'Item not found' })
  }
  res.json({ data: item })
})

// POST new item
app.post('/api/items', (req, res) => {
  const { name } = req.body
  if (!name) {
    return res.status(400).json({ error: 'Name is required' })
  }
  const newItem = { id: nextId++, name }
  items.push(newItem)
  res.status(201).json({ data: newItem })
})

// DELETE item
app.delete('/api/items/:id', (req, res) => {
  const index = items.findIndex(i => i.id === parseInt(req.params.id))
  if (index === -1) {
    return res.status(404).json({ error: 'Item not found' })
  }
  items.splice(index, 1)
  res.status(204).send()
})

// 404 handler for undefined routes
app.use((req, res) => {
  res.status(404).json({ error: 'Route not found' })
})

// Error handling middleware
app.use((err, req, res, next) => {
  console.error(err.stack)
  res.status(500).json({ error: 'Internal server error' })
})

app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`)
})

Inicie seu servidor:

npm start

Entendendo a Estrutura da API Backend em JavaScript

Esta configuração mínima de API REST em Node cobre o essencial:

Parsing de JSON: O Express 5 inclui express.json() como middleware integrado. Não são necessários pacotes externos (veja a documentação da API do Express).

Respostas Consistentes: Cada endpoint retorna JSON com uma propriedade data ou error. Esta previsibilidade ajuda o código frontend a lidar com respostas de forma uniforme.

Códigos de Status HTTP: A API usa códigos apropriados—200 para sucesso, 201 para recursos criados, 204 para exclusões bem-sucedidas, 400 para requisições inválidas, 404 para recursos não encontrados e 500 para erros do servidor.

Tratamento de Erros: O middleware de erro catch-all previne que erros de rota não tratados derrubem seu servidor.

Testando Seus Endpoints

Use curl ou qualquer cliente HTTP:

# Get all items
curl http://localhost:3000/api/items

# Get single item
curl http://localhost:3000/api/items/1

# Create item
curl -X POST http://localhost:3000/api/items \
  -H "Content-Type: application/json" \
  -d '{"name": "New item"}'

# Delete item
curl -X DELETE http://localhost:3000/api/items/1

O Que Isso Não Inclui

Este guia intencionalmente omite bancos de dados, autenticação e validação complexa. Essas preocupações são importantes para sistemas de produção, mas adicionam ruído quando você está aprendendo os fundamentos ou criando um protótipo rápido.

Quando estiver pronto para expandir, considere adicionar:

• Validação de entrada com uma biblioteca como Zod
• Variáveis de ambiente para configuração
• Uma conexão de banco de dados para persistência

Conclusão

Agora você tem uma API REST mínima funcional em Node.js com Express 5. O padrão aqui—respostas JSON consistentes, códigos de status adequados e tratamento centralizado de erros—escala bem à medida que sua API cresce. Comece com esta base e adicione complexidade apenas quando seu projeto exigir.

Perguntas Frequentes

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.