Construindo Sua Primeira API REST em Node.js: Um Guia Completo para Iniciantes

Introdução: Por que Node.js para Desenvolvimento Backend?

Se você vem acompanhando o projeto do servidor de agendamento (scheduler), já sabe que o Node.js é uma plataforma incrivelmente poderosa para construir aplicações server-side. Mas, se você está começando agora, pode estar se perguntando: por que Node.js? Por que não ficar com as linguagens server-side tradicionais?

A resposta está no modelo de I/O orientado a eventos e não-bloqueante do Node.js, que o torna incrivelmente eficiente para lidar com conexões concorrentes — perfeito para aplicações web modernas que precisam lidar com dados em tempo real, APIs e microsserviços.

Neste tutorial, vamos acompanhar a construção do seu primeiro servidor de API REST usando Node.js e o framework Restify. Ao final, você terá um servidor funcional capaz de aceitar requisições POST, armazenar dados e devolvê-los via requisições GET.

Passo 1: Instalando o Node.js e o NPM

Antes de escrever qualquer código, precisamos configurar nosso ambiente de desenvolvimento. O processo é simples:

No macOS (Método Recomendado)

Se você está em um Mac, recomendo fortemente usar o Homebrew — é a maneira mais fácil de gerenciar instalações do Node.js:

brew install node

Esse único comando vai instalar tanto o Node.js quanto o NPM (Node Package Manager), que vamos precisar para instalar frameworks e pacotes.

Verificação

Após a instalação, verifique se tudo está funcionando:

node --version
npm --version

Você deverá ver os números de versão de ambos, confirmando que a instalação foi bem-sucedida.

Passo 2: Entendendo a Escolha do Framework

O Node.js já vem com recursos nativos de servidor HTTP, mas escrever código de servidor HTTP puro pode ficar complicado rapidamente. É aí que entram frameworks como Restify e Express.

Restify vs. Express: Qual a Diferença?

• Express é um framework web completo que pode lidar com tudo, desde roteamento até templates, sendo ideal para construir aplicações web completas.
• Restify é um framework mais enxuto, projetado especificamente para construir APIs RESTful. Ele foca no essencial: endpoints, métodos HTTP e manipulação de JSON.

Para o nosso projeto de agendamento, estamos usando o Restify porque precisamos de um endpoint de API limpo, sem o overhead de um servidor web completo.

Passo 3: Construindo Seu Primeiro Servidor

Vamos começar com um servidor básico "Hello World" usando Restify:

var restify = require('restify');

var server = restify.createServer({
    name: 'scheduler-api'
});

server.get('/test', function(req, res, next) {
    res.send('Test endpoint working!');
    next();
});

server.listen(8080, function() {
    console.log('Server listening on port 8080');
});

Salve isso como index.js e execute com node index.js. Em seguida, visite http://localhost:8080/test no seu navegador — você deverá ver sua mensagem!

Passo 4: Entendendo GET vs POST

Antes de mergulharmos nas requisições POST, vamos esclarecer a diferença entre os métodos HTTP:

Requisições GET

GET é usado para recuperar dados do servidor. Você envia uma URL (opcionalmente com parâmetros de consulta), e o servidor responde com dados. Isso é o que acabamos de fazer com nosso endpoint /test.

Requisições POST

POST é usado para enviar dados ao servidor. Em vez de apenas solicitar dados, você está submetendo um payload que o servidor pode processar, armazenar ou sobre o qual pode agir. Isso é essencial para o nosso agendador, que precisa aceitar itens de agenda dos clientes.

Passo 5: Criando um Endpoint POST

Agora vamos adicionar um endpoint POST ao nosso servidor:

server.post('/upload/test', function(req, res, next) {
    console.log('Received POST request');
    console.log('Body:', req.body);
    res.send(200, { status: 'ok' });
    next();
});

Observe alguns pontos importantes:

• O primeiro parâmetro é o caminho do endpoint: /upload/test
• O segundo parâmetro é uma função de callback que trata a requisição
• req contém os dados da requisição recebida, incluindo o body
• res é usado para enviar respostas de volta ao cliente
• next() é importante para o encadeamento de middlewares no Restify

Passo 6: Testando Seu Endpoint POST

Você não consegue testar requisições POST no navegador como faz com GET — você precisa de um cliente HTTP adequado. Eu recomendo o Advanced REST Client, uma extensão do Chrome que torna o teste de APIs simples e intuitivo.

Configurando Sua Requisição

1. Defina o método como POST
2. Insira sua URL: http://localhost:8080/upload/test
3. Defina o Content-Type como application/json
4. Adicione seu payload JSON no body

Importante: A Sintaxe JSON Importa!

Ao montar payloads JSON manualmente, lembre-se de que o JSON requer aspas duplas para strings, não aspas simples:

{"test": "This is valid JSON"}

Não assim:

{'test': 'This will cause errors'}

Use ferramentas como JSONLint para validar seu JSON antes de enviar requisições.

Passo 7: Lendo e Armazenando Dados da Requisição

Agora que conseguimos receber requisições POST, vamos realmente armazenar os dados.

Para este tutorial, usaremos armazenamento em memória (que será reiniciado quando o servidor reiniciar — abordaremos armazenamento persistente com MongoDB no próximo tutorial).

// Declare a variable to store our data
var testData = [];

server.post('/upload/test', function(req, res, next) {
    // Extract the 'test' field from the request body
    var scheduleItem = req.body.test;
    
    // Add it to our array
    testData.push(scheduleItem);
    
    console.log('Stored item:', scheduleItem);
    console.log('Total items:', testData.length);
    
    res.send(200, { status: 'ok', message: 'Item stored successfully' });
    next();
});

Passo 8: Recuperando os Dados Armazenados

Armazenamos os dados, mas como recuperá-los? Vamos atualizar nosso endpoint GET:

server.get('/test', function(req, res, next) {
    // Return the entire array of stored items
    res.send(testData);
    next();
});

Agora você pode:

1. Fazer POST de múltiplos itens para /upload/test
2. Fazer GET em /test para recuperar todos os itens armazenados

Armadilhas Comuns e Como Evitá-las

1. Esquecer de Enviar uma Resposta

Se você não enviar uma resposta, o cliente ficará pendurado indefinidamente aguardando uma. Sempre encerre seus manipuladores de requisição com res.send().

2. Ignorar a Função next()

No Restify, sempre chame next() ao final dos seus manipuladores, a menos que você já tenha enviado uma resposta. Isso permite que o middleware continue o processamento.

3. Não Validar a Entrada

Sempre valide os dados recebidos antes de processá-los. Em produção, você vai querer verificar se os campos obrigatórios existem e estão no tipo correto.

O que vem a seguir?

Neste tutorial, abordamos:

• Instalar o Node.js e configurar seu ambiente
• Entender a diferença entre Restify e Express
• Criar endpoints GET e POST
• Testar APIs com o Advanced REST Client
• Ler payloads JSON e armazenar dados

Mas há uma grande limitação: nossos dados desaparecem quando o servidor reinicia. No próximo tutorial, vamos integrar o MongoDB para armazenamento persistente. O MongoDB é um banco de dados NoSQL que armazena dados em um formato similar a JSON, tornando-o uma escolha natural para aplicações Node.js.

Depois disso, começaremos a construir aplicações cliente que podem se comunicar com nossa API de agendamento, trazendo todo o sistema à vida.

Considerações Finais

Construir uma API REST pode parecer assustador no início, mas dividi-lo em passos pequenos e gerenciáveis torna isso totalmente alcançável. Agora você tem o conhecimento fundamental para construir APIs que podem aceitar dados, processá-los e devolvê-los aos clientes.

Lembre-se: a melhor maneira de aprender é fazendo. Modifique o código, experimente diferentes endpoints e não tenha medo de quebrar as coisas — é assim que aprendemos!

No próximo episódio, vamos mergulhar no MongoDB e aprender como tornar nossos dados persistentes. Até lá, boa programação!