Introdução

Prezados estudantes, bem-vindos à Aula 27 do nosso curso. Hoje, mergulharemos em um dos pilares mais robustos e significativos na construção de APIs: o roteamento HTTP, com foco nos métodos mais empregados: GET, POST, PUT e DELETE.

A Cozinha do Mundo Digital: Uma Analogia Prática

Imagine uma cozinha de restaurante movimentada, como a de um chef renomado. Clientes fazem diversos tipos de pedidos, e cada pedido exige uma ação específica da equipe:

• Quando você pede para ver o cardápio ou o prato do dia, é como uma solicitação para LER informações, sem alterar nada.
• Quando você faz um novo pedido, por exemplo, um prato que ainda não está na sua mesa, você está CRIANDO algo novo.
• Se você decide mudar um ingrediente do seu prato já pedido ou alterar o ponto da carne, você está ATUALIZANDO algo existente.
• E, infelizmente, se você cancela um pedido por completo, você está DELETANDO-o da fila de produção.

Em nossa API, cada uma dessas ações – ler, criar, atualizar e deletar – corresponde a um “verbo” HTTP específico que direciona a requisição para a função correta no nosso servidor. Essa é a essência do roteamento!

Por que o Roteamento é Primordial para APIs Modernas?

O roteamento é a espinha dorsal de qualquer API bem arquitetada. Ele não apenas direciona o tráfego de requisições, mas também confere clareza semântica e previsibilidade às interações entre clientes e servidores. Sem um sistema de roteamento bem definido, uma API seria um caos incompreensível, sem um mapa claro de como acessar suas funcionalidades. É o que possibilita que aplicações front-end, outros microsserviços e até mesmo sistemas móveis saibam exatamente como interagir e manipular os recursos fornecidos.

O que Exatamente Você Vai Desenvolver Nesta Aula?

Nesta aula, iremos construir um pequeno servidor Node.js utilizando o framework Express.js. Nosso objetivo é criar um conjunto de rotas para gerenciar um recurso simples, como uma lista de “itens” (pense em tarefas ou produtos). Você aprenderá a definir rotas que respondem a requisições GET, POST, PUT e DELETE, manipulando dados em memória para simular uma aplicação real.

Contexto no Ecossistema Node.js/Express

No universo Node.js, o Express.js é o framework de facto para desenvolver APIs RESTful. Ele nos oferece uma API concisa e poderosa para definir rotas de maneira elegante e eficiente. A compreensão profunda do roteamento no Express.js é um conhecimento valioso que irá acelerar significativamente o seu desenvolvimento e a qualidade das suas aplicações.

Conceito Fundamental

No cerne da comunicação web, temos o Protocolo de Transferência de Hipertexto (HTTP). Ele define os métodos de requisição, que são verbos que indicam a ação desejada a ser executada em um recurso identificado por uma URL. Esses métodos são a fundação do roteamento em qualquer API RESTful.

Explicação Detalhada do Conceito Técnico

Cada método HTTP tem uma semântica específica que o torna apropriado para diferentes tipos de operações. Vamos explorar os mais relevantes:

• GET (Retrieve):
  • Propósito: Solicitar dados de um recurso especificado.
  • Características: É um método seguro (não altera o estado do servidor) e idempotente (múltiplas requisições idênticas produzem o mesmo resultado final no servidor, embora a resposta possa variar ligeiramente).
  • Uso: Obter a lista de todos os usuários, recuperar detalhes de um produto específico, baixar um arquivo.
• POST (Create):
  • Propósito: Enviar dados para o servidor para criar um novo recurso ou para processar dados que podem ter efeitos colaterais.
  • Características: Não é idempotente (enviar o mesmo POST múltiplas vezes pode criar múltiplos recursos idênticos) e não é seguro.
  • Uso: Cadastrar um novo usuário, enviar um formulário de contato, fazer um pedido de compra.
• PUT (Update/Replace):
  • Propósito: Atualizar um recurso existente com os dados fornecidos na requisição, ou criar o recurso se ele não existir na URL especificada.
  • Características: É idempotente (enviar o mesmo PUT múltiplas vezes resultará no mesmo estado do recurso).
  • Uso: Atualizar completamente os dados de um usuário (substituindo o recurso antigo pelos novos dados), enviar um novo rascunho de um artigo.
• DELETE (Remove):
  • Propósito: Excluir um recurso especificado.
  • Características: É idempotente (excluir um recurso que já não existe não causa um novo erro ou alteração, embora a primeira tentativa de exclusão seja a única que realmente remove o recurso).
  • Uso: Remover um item do carrinho de compras, apagar um perfil de usuário.

Terminologia Correta da Indústria

• Verbos HTTP (ou Métodos HTTP): Os termos GET, POST, PUT, DELETE, PATCH, etc., que definem a ação.
• Recurso: Qualquer dado ou serviço que pode ser acessado através de uma URL (Uniform Resource Locator). Ex: /users, /products/123.
• Idempotência: A propriedade de uma operação que, quando executada várias vezes, produz o mesmo resultado no estado do sistema após a primeira execução bem-sucedida. GET, PUT, DELETE são idempotentes. POST não é.
• Segurança: No contexto HTTP, uma operação é “segura” se ela não causa efeitos colaterais no servidor. Apenas GET é considerado seguro.

Casos de Uso Reais em Produção

Em sistemas empresariais, estes métodos são amplamente empregados:

• Um e-commerce utiliza GET /products para listar todos os produtos, GET /products/{id} para detalhes de um produto, POST /orders para criar um novo pedido, PUT /users/{id} para atualizar o perfil do usuário e DELETE /cart/{id} para remover um item do carrinho.
• Sistemas de gerenciamento de conteúdo (CMS) usam POST /articles para publicar um novo artigo, PUT /articles/{id} para revisões e DELETE /articles/{id} para excluir artigos antigos.

Como Isso se Integra com Outras Tecnologias?

O roteamento é a ponte que conecta o front-end (desenvolvido em React, Angular, Vue, etc.) com o back-end. Quando o usuário clica em um botão no front-end para “salvar”, o código JavaScript correspondente envia uma requisição POST ou PUT para a rota apropriada do nosso back-end. O back-end, por sua vez, processa essa requisição, interage com um banco de dados (MongoDB, PostgreSQL, MySQL) para persistir ou recuperar os dados e envia uma resposta de volta ao front-end.

Vantagens e Desvantagens

• Vantagens:
  • Clareza Semântica: Cada método comunica claramente a intenção da operação, tornando a API mais fácil de entender e usar.
  • Padronização: Segue um padrão amplamente aceito na web, facilitando a interoperabilidade entre diferentes sistemas.
  • Eficiência: Métodos como GET podem ser armazenados em cache por proxies e navegadores, reduzindo a carga do servidor e melhorando a performance.
  • Ferramentas e Bibliotecas: Muitas ferramentas e bibliotecas de desenvolvimento são construídas com base nessa semântica, simplificando a implementação.
• Desvantagens:
  • Mal-uso: Se não forem aplicados corretamente, podem levar a APIs confusas e que violam os princípios REST. Por exemplo, usar POST para obter dados que deveriam ser um GET.
  • Over-engenharia: Em APIs muito simples, a aderência estrita a todos os princípios REST pode parecer excessiva, mas é uma prática recomendada para escalabilidade e manutenção.

Implementação Prática

Agora, vamos colocar as mãos na massa e desenvolver um servidor Express.js que implementa as rotas GET, POST, PUT e DELETE para gerenciar uma coleção de itens.

Configuração do Ambiente

Primeiro, crie uma nova pasta para o seu projeto e inicialize um projeto Node.js:

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

Crie um arquivo chamado server.js na raiz da pasta do projeto.

Código Funcional COMPLETO

Este código representa um servidor Node.js com Express.js, que gerencia uma lista de itens em memória. Ele é compatível com qualquer ambiente Node.js, incluindo servidores Linux com Node.js instalado (como um VPS ou servidor dedicado da HostGator que suporte Node.js). Planos compartilhados como o “HostGator Plano M” geralmente não oferecem suporte nativo a Node.js sem configurações avançadas ou uso de contêineres como Docker, que estariam em um ambiente mais controlado como um VPS.

// server.js

// 1. Importa o módulo Express.js, que é um framework para construir aplicações web e APIs.
const express = require('express');
// 2. Cria uma instância do aplicativo Express.
const app = express();
// 3. Define a porta em que o servidor irá escutar.
// Recomenda-se usar variáveis de ambiente para a porta em ambientes de produção.
const PORT = process.env.PORT || 3000;
// 4. Middleware para processar requisições com corpo JSON.
// Isso é crucial para que o Express possa ler dados enviados via POST ou PUT no formato JSON.
app.use(express.json());
// 5. Array em memória para armazenar nossos "itens".
// Em uma aplicação real, estes dados viriam de um banco de dados.
let items = [
    { id: 1, nome: 'Caneta', descricao: 'Escreve suavemente na cor azul.' },
    { id: 2, nome: 'Caderno', descricao: 'Cem folhas pautadas.' },
    { id: 3, nome: 'Mochila', descricao: 'Para transportar livros e laptop.' }
];
let nextId = 4; // Um contador para gerar IDs únicos para novos itens.
// ----------------------------------------------------
// ROTAS DA API
// ----------------------------------------------------
// 6. Rota GET: Listar todos os itens
// Endpoint: GET /items
// Objetivo: Retornar todos os itens disponíveis.
app.get('/items', (req, res) => {
    // 6.1. Logging: Registrar a requisição para fins de depuração ou auditoria.
    console.log([${new Date().toISOString()}] GET /items - Requisição recebida.);
    // 6.2. Envia a lista de itens como resposta no formato JSON.
    // O status 200 (OK) é o padrão para requisições GET bem-sucedidas.
    res.status(200).json(items);
    console.log([${new Date().toISOString()}] GET /items - ${items.length} itens retornados.);
});
// 7. Rota GET: Obter um item por ID
// Endpoint: GET /items/:id
// Objetivo: Retornar os detalhes de um item específico, identificado pelo seu ID.
app.get('/items/:id', (req, res) => {
    // 7.1. Extrai o ID do item dos parâmetros da URL. req.params.id sempre retorna uma string.
    const itemId = parseInt(req.params.id);
    console.log([${new Date().toISOString()}] GET /items/${itemId} - Requisição recebida.);
    // 7.2. Busca o item no array 'items' usando o ID.
    const item = items.find(i => i.id === itemId);
    // 7.3. Tratamento de Erro: Se o item não for encontrado, retorna status 404 (Not Found).
    if (!item) {
        console.warn([${new Date().toISOString()}] GET /items/${itemId} - Item não encontrado.);
        return res.status(404).json({ message: 'Item não encontrado.' });
    }
    // 7.4. Se o item for encontrado, retorna-o com status 200 (OK).
    res.status(200).json(item);
    console.log([${new Date().toISOString()}] GET /items/${itemId} - Item '${item.nome}' retornado.);
});
// 8. Rota POST: Criar um novo item
// Endpoint: POST /items
// Objetivo: Adicionar um novo item à coleção.
app.post('/items', (req, res) => {
    // 8.1. Extrai os dados do novo item do corpo da requisição.
    // req.body contém o objeto JSON enviado pelo cliente.
    const { nome, descricao } = req.body;
    console.log([${new Date().toISOString()}] POST /items - Requisição recebida com dados:, req.body);
    // 8.2. Validação de Entrada: Verifica se os campos 'nome' e 'descricao' estão presentes.
    if (!nome || !descricao) {
        console.error([${new Date().toISOString()}] POST /items - Dados inválidos: nome ou descrição ausente.);
        return res.status(400).json({ message: 'Nome e descrição são campos obrigatórios.' });
    }
    // 8.3. Cria um novo objeto item com um ID único.
    const newItem = {
        id: nextId++, // Incrementa o nextId para a próxima requisição.
        nome,
        descricao
    };
    // 8.4. Adiciona o novo item ao array.
    items.push(newItem);
    // 8.5. Retorna o item recém-criado com status 201 (Created).
    res.status(201).json(newItem);
    console.log([${new Date().toISOString()}] POST /items - Item '${newItem.nome}' criado com ID ${newItem.id}.);
});
// 9. Rota PUT: Atualizar um item existente
// Endpoint: PUT /items/:id
// Objetivo: Substituir completamente um item existente, identificado pelo seu ID, pelos novos dados.
app.put('/items/:id', (req, res) => {
    // 9.1. Extrai o ID e os novos dados do item.
    const itemId = parseInt(req.params.id);
    const { nome, descricao } = req.body;
    console.log([${new Date().toISOString()}] PUT /items/${itemId} - Requisição recebida com dados:, req.body);
    // 9.2. Validação de Entrada: Verifica se os campos 'nome' e 'descricao' estão presentes.
    if (!nome || !descricao) {
        console.error([${new Date().toISOString()}] PUT /items/${itemId} - Dados inválidos: nome ou descrição ausente.);
        return res.status(400).json({ message: 'Nome e descrição são campos obrigatórios para atualização.' });
    }
    // 9.3. Encontra o índice do item no array.
    const itemIndex = items.findIndex(i => i.id === itemId);
    // 9.4. Tratamento de Erro: Se o item não for encontrado, retorna status 404 (Not Found).
    if (itemIndex === -1) {
        console.warn([${new Date().toISOString()}] PUT /items/${itemId} - Item não encontrado para atualização.);
        return res.status(404).json({ message: 'Item não encontrado para atualizar.' });
    }
    // 9.5. Atualiza o item no array.
    const updatedItem = {
        id: itemId,
        nome,
        descricao
    };
    items[itemIndex] = updatedItem;
    // 9.6. Retorna o item atualizado com status 200 (OK).
    res.status(200).json(updatedItem);
    console.log([${new Date().toISOString()}] PUT /items/${itemId} - Item '${updatedItem.nome}' atualizado.);
});
// 10. Rota DELETE: Excluir um item
// Endpoint: DELETE /items/:id
// Objetivo: Remover um item da coleção, identificado pelo seu ID.
app.delete('/items/:id', (req, res) => {
    // 10.1. Extrai o ID do item a ser deletado.
    const itemId = parseInt(req.params.id);
    console.log([${new Date().toISOString()}] DELETE /items/${itemId} - Requisição recebida.);
    // 10.2. Encontra o índice do item no array.
    const itemIndex = items.findIndex(i => i.id === itemId);
    // 10.3. Tratamento de Erro: Se o item não for encontrado, retorna status 404 (Not Found).
    if (itemIndex === -1) {
        console.warn([${new Date().toISOString()}] DELETE /items/${itemId} - Item não encontrado para exclusão.);
        return res.status(404).json({ message: 'Item não encontrado para deletar.' });
    }
    // 10.4. Remove o item do array. O método splice remove um ou mais elementos de um array.
    const deletedItem = items.splice(itemIndex, 1);
    // 10.5. Retorna status 204 (No Content) para indicar que a requisição foi bem-sucedida, mas não há conteúdo para retornar.
    res.status(204).send(); // send() é usado com 204 status, pois não há corpo na resposta.
    console.log([${new Date().toISOString()}] DELETE /items/${itemId} - Item '${deletedItem[0].nome}' excluído.);
});
// 11. Middleware para lidar com rotas não encontradas (404)
// Esta middleware deve ser o último a ser definido, depois de todas as suas rotas.
app.use((req, res, next) => {
    console.warn([${new Date().toISOString()}] 404 Not Found - Rota ${req.method} ${req.url} não encontrada.);
    res.status(404).json({ message: 'Recurso não encontrado.' });
});
// 12. Middleware de tratamento de erros global
// Este middleware captura quaisquer erros que ocorram nas rotas.
app.use((err, req, res, next) => {
    console.error([${new Date().toISOString()}] ERRO INTERNO DO SERVIDOR:, err.stack);
    res.status(500).json({ message: 'Ocorreu um erro interno no servidor.' });
});
// 13. Inicia o servidor e o faz escutar na porta definida.
app.listen(PORT, () => {
    console.log([${new Date().toISOString()}] Servidor Express.js iniciado na porta ${PORT}.);
    console.log([${new Date().toISOString()}] Acesse: http://localhost:${PORT});
});

Melhores Práticas Enterprise

• Estrutura de Pastas: Para projetos maiores, organize o código em módulos (routes/, controllers/, models/). Aqui, mantivemos simples para foco no roteamento.
• Validação de Entrada Robusta: Usar bibliotecas como Joi ou express-validator para validar o corpo da requisição de forma mais complexa e padronizada.
• Error Handling Otimizado: Implementar middlewares de tratamento de erros globais e específicos, retornando mensagens claras e códigos de status HTTP apropriados.
• Logging Profissional: Em vez de console.log, use bibliotecas como Winston ou Morgan (para logs de requisição HTTP) para logs estruturados e configuráveis.
• Persistência de Dados: Conectar a um banco de dados (MongoDB, PostgreSQL, MySQL) para que os dados persistam após o servidor ser reiniciado. Nossa solução é em memória e serve apenas para fins didáticos.
• Segurança: Implementar autenticação (JWT, OAuth) e autorização para proteger endpoints sensíveis.

Configurações Específicas para HostGator Plano M

É importante destacar que o “HostGator Plano M” é um plano de hospedagem compartilhada que tipicamente foca em tecnologias como PHP e MySQL. Embora alguns provedores possam oferecer soluções paliativas ou para VPS/Servidores Dedicados, não há suporte nativo para Node.js em planos de hospedagem compartilhada padrão da HostGator sem um ambiente específico (como um VPS ou servidor dedicado com Node.js instalado e configurado). O código acima é um programa Node.js padrão e funcionará em qualquer servidor (local, VPS, dedicado) que tenha o ambiente Node.js configurado e a porta desejada livre. Se você planeja hospedar aplicações Node.js, é fundamental optar por um plano de hospedagem que explicitamente ofereça suporte a Node.js ou um VPS onde você tenha controle total sobre a instalação e configuração do ambiente.

Testes Básicos Incluídos

Para testar sua API, você pode usar ferramentas como curl (terminal), Postman ou Insomnia. Certifique-se de que seu servidor está rodando (node server.js) antes de executar os comandos.

# Testar GET: Listar todos os itens
curl http://localhost:3000/items


Testar GET: Obter um item específico (ID 1)



    
📚 Informações da Aula

    
Curso: API Completo - Node.js & Express

    
Tempo estimado: 25 minutos

    
Pré-requisitos: JavaScript básico



curl http://localhost:3000/items/1


Testar POST: Criar um novo item

curl -X POST -H "Content-Type: application/json" -d '{"nome": "Teclado", "descricao": "Mecanico, RGB."}' http://localhost:3000/items


Testar PUT: Atualizar um item existente (ID 1, supondo que já exista)

curl -X PUT -H "Content-Type: application/json" -d '{"nome": "Caneta Nova", "descricao": "Gel, cor preta."}' http://localhost:3000/items/1


Testar DELETE: Excluir um item (ID 2, supondo que exista)

curl -X DELETE http://localhost:3000/items/2

Exercício Hands-On

A teoria e a prática são poderosas, mas a aplicação independente é onde o verdadeiro aprendizado se manifesta.

Desafio Prático para Implementar Sozinho

Seu desafio é adicionar uma nova funcionalidade à nossa API de itens. Implemente uma rota PATCH que permita a atualização parcial de um item.

• O método PATCH é usado para aplicar modificações parciais a um recurso. Diferente do PUT, ele não exige que o corpo da requisição contenha o recurso completo.
• Sua rota deve aceitar requisições PATCH para /items/:id.
• O corpo da requisição pode conter nome ou descricao (ou ambos).
• A rota deve atualizar apenas os campos que forem fornecidos no corpo da requisição, mantendo os outros campos inalterados.
• Garanta validação e tratamento de erros (item não encontrado, corpo vazio).

Solução Detalhada Passo a Passo

Adicione o seguinte bloco de código ao seu arquivo server.js, antes dos middlewares de 404 e erro global.

// 11. Rota PATCH: Atualizar parcialmente um item
// Endpoint: PATCH /items/:id
// Objetivo: Atualizar apenas os campos fornecidos de um item existente.
app.patch('/items/:id', (req, res) => {
    const itemId = parseInt(req.params.id);
    const updates = req.body; // 'updates' pode conter nome, descricao ou ambos.
    console.log([${new Date().toISOString()}] PATCH /items/${itemId} - Requisição recebida com dados:, updates);

    // 11.1. Verifica se o corpo da requisição não está vazio.
    if (Object.keys(updates).length === 0) {
        console.error([${new Date().toISOString()}] PATCH /items/${itemId} - Corpo da requisição vazio.);
        return res.status(400).json({ message: 'Nenhum campo para atualizar foi fornecido.' });
    }
    const itemIndex = items.findIndex(i => i.id === itemId);
    if (itemIndex === -1) {
        console.warn([${new Date().toISOString()}] PATCH /items/${itemId} - Item não encontrado para atualização parcial.);
        return res.status(404).json({ message: 'Item não encontrado para atualização parcial.' });
    }
    // 11.2. Cria um novo objeto com as propriedades existentes e as atualizações.
    // Isso garante que apenas os campos fornecidos em 'updates' sejam alterados.
    items[itemIndex] = { ...items[itemIndex], ...updates };
    const updatedItem = items[itemIndex];
    res.status(200).json(updatedItem);
    console.log([${new Date().toISOString()}] PATCH /items/${itemId} - Item '${updatedItem.nome}' atualizado parcialmente.);
});

Como Testar e Validar o Resultado

Reinicie seu servidor Node.js e use curl para testar a nova rota PATCH:

# Supondo que você tem um item com ID 1:

GET para ver o estado atual

curl http://localhost:3000/items/1


Testar PATCH: Atualizar apenas a descrição do item com ID 1

curl -X PATCH -H "Content-Type: application/json" -d '{"descricao": "Caneta de tinta permanente, azul indigo."}' http://localhost:3000/items/1


Testar PATCH: Atualizar apenas o nome do item com ID 1

curl -X PATCH -H "Content-Type: application/json" -d '{"nome": "Caneta Gel Plus"}' http://localhost:3000/items/1


Testar PATCH: Atualizar ambos os campos do item com ID 1

curl -X PATCH -H "Content-Type: application/json" -d '{"nome": "Caneta Master", "descricao": "Tinta gel preta, 0.7mm."}' http://localhost:3000/items/1


GET novamente para verificar as alterações

curl http://localhost:3000/items/1

Verifique o corpo da resposta e os logs do seu servidor para confirmar que as atualizações parciais foram aplicadas corretamente.

Troubleshooting dos Erros Mais Comuns

• 404 Not Found:
  • Verifique a URL: Você digitou a URL corretamente? (Ex: /items vs /item).
  • Método HTTP: Você está usando o método HTTP correto para a rota? (Ex: POST em vez de GET).
  • Ordem das Rotas: No Express, a ordem importa. Rotas mais específicas devem vir antes das mais genéricas.
• 400 Bad Request:
  • Corpo da Requisição: O JSON que você está enviando está bem formatado? (Use um validador de JSON online se tiver dúvidas).
  • Campos Obrigatórios: Você está fornecendo todos os campos necessários que a API espera? (Ex: nome e descricao para POST e PUT).
• 500 Internal Server Error:
  • Erro no Código: Algo deu errado no seu JavaScript. Verifique os logs do servidor para a mensagem de erro detalhada e a pilha de chamadas (stack trace).
  • Variáveis Não Definidas: Tentando acessar uma propriedade de um objeto undefined.
• Servidor Não Inicia (Porta em Uso):
  • Mensagem de Erro: EADDRINUSE. Isso significa que outra aplicação já está usando a porta 3000. Você pode matar o processo anterior ou mudar a porta do seu servidor.
  • No Linux/macOS: lsof -i :3000 para ver qual processo está usando a porta, depois kill -9 .

Próximos Passos Sugeridos

Para aprimorar ainda mais suas habilidades e esta API:

• Persistência de Dados: Integre a API com um banco de dados real (MongoDB com Mongoose, ou PostgreSQL com Sequelize) para que os dados não sejam perdidos ao reiniciar o servidor.
• Autenticação e Autorização: Adicione JWT (JSON Web Tokens) para proteger suas rotas, permitindo que apenas usuários autenticados acessem ou modifiquem recursos.
• Testes Automatizados: Escreva testes unitários e de integração para suas rotas usando frameworks como Jest ou Mocha/Chai, garantindo a robustez do seu código.
• Documentação da API: Use ferramentas como Swagger/OpenAPI para gerar automaticamente documentação interativa para sua API.
• Implantação (Deploy): Aprenda a hospedar sua API em plataformas de nuvem como Heroku, Vercel (para back-ends sem servidor), ou um VPS dedicado.

Parabéns por completar esta aula! Você dominou os fundamentos do roteamento HTTP, um conhecimento indispensável para qualquer desenvolvedor de back-end.