Construye tu primera API REST con Node.js: guía completa para principiantes

Introducción: ¿Por qué Node.js para el desarrollo backend?

Si has estado siguiendo el proyecto del servidor de nodos del scheduler, ya sabes que Node.js es una plataforma increíblemente potente para crear aplicaciones del lado del servidor. Pero si estás empezando, puede que te preguntes: ¿por qué Node.js? ¿Por qué no seguir con los lenguajes tradicionales del lado del servidor?

La respuesta está en el modelo de E/S basado en eventos y sin bloqueo de Node.js, que lo hace increíblemente eficiente para gestionar conexiones concurrentes, perfecto para aplicaciones web modernas que necesitan manejar datos en tiempo real, APIs y microservicios.

En este tutorial, recorreremos paso a paso la creación de tu primer servidor REST API con Node.js y el framework Restify. Al final, tendrás un servidor funcional capaz de aceptar solicitudes POST, almacenar datos y devolverlos mediante solicitudes GET.

Paso 1: Instalar Node.js y NPM

Antes de escribir cualquier código, necesitamos configurar nuestro entorno de desarrollo. El proceso es sencillo:

En macOS (método recomendado)

Si estás en un Mac, te recomiendo encarecidamente usar Homebrew: es la forma más fácil de gestionar las instalaciones de Node.js:

brew install node

Este único comando instalará tanto Node.js como NPM (Node Package Manager), que necesitaremos para instalar frameworks y paquetes.

Verificación

Tras la instalación, verifica que todo funciona:

node --version
npm --version

Deberías ver los números de versión de ambos, lo que confirma que la instalación se ha realizado correctamente.

Paso 2: Entender la elección del framework

Node.js incluye capacidades de servidor HTTP integradas, pero escribir código de servidor HTTP en bruto puede complicarse rápidamente. Ahí es donde entran en juego frameworks como Restify y Express.

Restify frente a Express: ¿cuál es la diferencia?

• Express es un framework web con todas las funciones que puede gestionar desde el enrutamiento hasta el templating, lo que lo hace ideal para construir aplicaciones web completas.
• Restify es un framework más ligero, diseñado específicamente para construir APIs RESTful. Se centra en lo esencial: endpoints, métodos HTTP y manejo de JSON.

Para nuestro proyecto de scheduler, usamos Restify porque necesitamos un endpoint de API limpio sin la sobrecarga de un servidor web completo.

Paso 3: Construir tu primer servidor

Comencemos con un servidor básico de «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();
});

Guarda esto como index.js y ejecútalo con node index.js. Luego visita http://localhost:8080/test en tu navegador—¡deberías ver tu mensaje!

Paso 4: Entender GET frente a POST
Antes de profundizar en las peticiones POST, aclaremos la diferencia entre los métodos HTTP:

Peticiones GET
GET se utiliza para recuperar datos del servidor. Envías una URL (opcionalmente con parámetros de consulta) y el servidor responde con datos. Esto es lo que acabamos de hacer con nuestro endpoint /test.

Peticiones POST
POST se utiliza para enviar datos al servidor. En lugar de simplemente solicitar datos, estás enviando un payload que el servidor puede procesar, almacenar o sobre el que puede actuar. Esto es esencial para nuestro scheduler, que necesita aceptar elementos de programación por parte de los clientes.

Paso 5: Crear un endpoint POST
Ahora vamos a añadir un endpoint POST a nuestro 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();
});
Observa algunas cosas clave:

El primer parámetro es la ruta del endpoint: /upload/test
El segundo parámetro es una función callback que gestiona la petición
req contiene los datos de la petición entrante, incluido el body
res se utiliza para enviar respuestas de vuelta al cliente
next() es importante para el encadenamiento de middleware en Restify
Paso 6: Probar tu endpoint POST
No puedes probar peticiones POST en tu navegador como las peticiones GET—necesitas un cliente HTTP adecuado. Te recomiendo Advanced REST Client, una extensión de Chrome que hace que probar APIs sea simple e intuitivo.
Configurar tu petición

Establece el método a POST
Introduce tu URL: http://localhost:8080/upload/test
Establece Content-Type a application/json
Añade tu payload JSON en el body
Importante: ¡La sintaxis JSON importa!
Cuando crees payloads JSON manualmente, recuerda que JSON requiere comillas dobles para las cadenas, no comillas simples:
{"test": "This is valid JSON"}
No esto:
{'test': 'This will cause errors'}
Usa herramientas como JSONLint para validar tu JSON antes de enviar peticiones.
Paso 7: Leer y almacenar datos de la petición
Ahora que podemos recibir peticiones POST, vamos a almacenar realmente los datos.
Para este tutorial, usaremos almacenamiento en memoria (que se reiniciará cuando el servidor se reinicie; cubriremos el almacenamiento persistente con MongoDB en el 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();
});
Paso 8: Recuperar los datos almacenados
Hemos almacenado datos, pero ¿cómo los recuperamos? Actualicemos nuestro endpoint GET:
server.get('/test', function(req, res, next) {
    // Return the entire array of stored items
    res.send(testData);
    next();
});
Ahora puedes:

Realizar POST con varios elementos a /upload/test
Realizar GET a /test para recuperar todos los elementos almacenados
Errores comunes y cómo evitarlos
1. Olvidar enviar una respuesta
Si no envías una respuesta, el cliente quedará esperando indefinidamente. Termina siempre tus manejadores de peticiones con res.send().
2. Ignorar la función next()
En Restify, llama siempre a next() al final de tus manejadores a menos que ya hayas enviado una respuesta. Esto permite que el middleware continúe procesando.
3. No validar la entrada
Valida siempre los datos entrantes antes de procesarlos. En producción, querrás comprobar que los campos obligatorios existen y son del tipo correcto.
¿Qué sigue?
En este tutorial, hemos cubierto:

Instalar Node.js y configurar tu entorno
Entender Restify frente a Express
Construir endpoints GET y POST
Probar APIs con Advanced REST Client
Leer cargas útiles JSON y almacenar datos
Pero hay una limitación importante: nuestros datos desaparecen cuando el servidor se reinicia. En el próximo tutorial, integraremos MongoDB para el almacenamiento persistente. MongoDB es una base de datos NoSQL que almacena datos en un formato similar a JSON, lo que la convierte en una elección natural para aplicaciones Node.js.
Después de eso, empezaremos a construir aplicaciones cliente que puedan comunicarse con nuestra API de scheduler, dando vida a todo el sistema.
Reflexiones finales
Construir una API REST puede parecer abrumador al principio, pero dividirlo en pasos pequeños y manejables lo hace completamente alcanzable. Ahora tienes los conocimientos fundamentales para construir APIs que puedan aceptar datos, procesarlos y servirlos de vuelta a los clientes.
Recuerda: la mejor forma de aprender es haciéndolo. Modifica el código, experimenta con diferentes endpoints y no temas romper cosas: ¡así es como aprendemos!
En la próxima entrega, nos sumergiremos en MongoDB y aprenderemos a hacer que nuestros datos sean persistentes. Hasta entonces, ¡feliz programación!