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

Introdução: por que usar Node.js no desenvolvimento backend?

Se você vem acompanhando o projeto do servidor de agendamento em Node, já sabe que o Node.js é uma plataforma incrivelmente poderosa para criar aplicações do lado do servidor. Mas, se está começando, talvez esteja se perguntando: por que Node.js? Por que não usar as linguagens tradicionais do lado do servidor?

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

Neste tutorial, vamos criar seu primeiro servidor de API REST usando Node.js e o framework Restify. Ao final, você terá um servidor funcional capaz de receber requisições POST, armazenar dados e disponibilizá-los novamente por meio de requisições GET.

Etapa 1: instalando Node.js e NPM

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

No macOS (método recomendado)

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

brew install node

Esse único comando instala o Node.js e o NPM (Gerenciador de Pacotes do Node), que precisaremos usar 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 concluída com sucesso.

Etapa 2: entendendo a escolha do framework

O Node.js inclui recursos nativos para criar servidores HTTP, mas escrever código de servidor HTTP do zero pode se tornar complicado rapidamente. É nesse ponto 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, tornando-o ideal para criar aplicações web completas.
• Restify é um framework mais enxuto, criado especificamente para desenvolver APIs RESTful. Ele se concentra no essencial: endpoints, métodos HTTP e manipulação de JSON.

Em nosso projeto de agendamento, estamos usando Restify porque precisamos de um endpoint de API simples, sem a carga adicional de um servidor web completo.

Etapa 3: criando 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();
});

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

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

Etapa 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 os 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 agendamento dos clientes.

Etapa 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

Etapa 6: Testando seu Endpoint POST

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

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 criar payloads JSON manualmente, lembre-se de que o JSON exige aspas duplas para strings, não aspas simples:

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

Não isso:

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

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

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

Agora que podemos 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 o 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 Dados Armazenados

Armazenamos 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. Esquecendo de Enviar uma Resposta

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

2. Ignorando a Função next()

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

3. Não Validando 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 são do tipo correto.

O que vem a seguir?

Neste tutorial, abordamos:

• Instalando o Node.js e configurando seu ambiente
• Entendendo Restify vs. Express
• Construindo endpoints GET e POST
• Testando APIs com o Advanced REST Client
• Lendo payloads JSON e armazenando dados

Mas há uma grande limitação: nossos dados desaparecem quando o servidor reinicia. No próximo tutorial, integraremos 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, dando vida a todo o sistema.

Considerações Finais

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

Lembre-se: a melhor maneira de aprender é fazendo. Modifique o código, experimente diferentes endpoints e não tenha medo de quebrar 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!