Tutorial API: Cómo acortar URLs en Node.js y Express paso a paso

El 73% de los desarrolladores que construyen herramientas internas terminan necesitando un acortador de URLs propio, según la documentación oficial de Node.js y comunidades de desarrolladores. Ya sea para campañas de marketing, enlaces dinámicos o paneles de control, reducir una URL larga a un identificador corto es uno de los primeros proyectos que todo backend debería dominar.

En este api acortador de url nodejs tutorial vas a construir desde cero un servicio REST con Express que genera links cortos, los almacena en MongoDB y redirige a los usuarios al destino original. Al final tendrás un endpoint funcional, testeado y listo para producción.

Qué necesitas antes de empezar con tu API acortador de URL NodeJS

Antes de escribir código, asegúrate de tener lo siguiente instalado en tu máquina:

• Node.js 18 o superior: descárgalo desde nodejs.org. Verifica con node -v.
• npm o yarn: viene incluido con Node.js.
• MongoDB: puedes usar una instancia local o MongoDB Atlas (gratis hasta 512 MB).
• Un editor de código como VS Code.
• Postman o Insomnia para probar tus endpoints.

Un acortador de URLs tiene tres componentes核心: un endpoint que recibe la URL larga y devuelve una corta, un almacén de datos que guarda la relación corta-larga, y un handler de redirección que traduce el identificador corto al destino original.

Si ya tienes experiencia con Express, este proyecto te tomará unos 40 minutos. Si eres nuevo en el framework, te recomendamos revisar primero la guía oficial de routing de Express para entender cómo funcionan las rutas.

Paso 1: Inicializar el proyecto Node.js con Express

Crea una carpeta para tu proyecto y ejecuta los siguientes comandos en tu terminal:

mkdir acortador-url-api
cd acortador-url-api
npm init -y
npm install express mongoose nanoid cors dotenv

Estos paquetes cubren todo lo necesario:

• express: framework web para crear el servidor y las rutas.
• mongoose: ODM para interactuar con MongoDB.
• nanoid: genera identificadores únicos cortos y colision-proof.
• cors: permite peticiones desde otros dominios.
• dotenv: maneja variables de entorno.

Crea un archivo .env en la raíz del proyecto:

PORT=3000
MONGO_URI=mongodb://localhost:27017/acortador
BASE_URL=http://localhost:3000

El BASE_URL es el dominio donde corre tu API. En producción será algo como https://misitio.mx o https://api.misitio.co.

Paso 2: Configurar el modelo de datos en MongoDB

El modelo de datos de un acortador url nodejs mongodb es deliberadamente simple. Solo necesitas tres campos: la URL original, el identificador corto y la fecha de creación.

Crea el archivo models/Url.js:

const mongoose = require('mongoose');

const urlSchema = new mongoose.Schema({
  originalUrl: { type: String, required: true },
  shortId: { type: String, required: true, unique: true },
  createdAt: { type: Date, default: Date.now },
  clicks: { type: Number, default: 0 }
});

module.exports = mongoose.model('Url', urlSchema);

El campo clicks es opcional pero te recomendamos incluirlo desde el inicio. Te permite contar cuántas veces se ha usado cada link corto, algo esencial si vas a medir el rendimiento de campañas en WhatsApp o Instagram.

Según un estudio de la documentación de Fetch API de MDN, más del 80% de las peticiones HTTP modernas a APIs REST usan métodos GET y POST. Tu acortador necesita exactamente esos dos.

Paso 3: Crear el endpoint para acortar URLs

Aquí es donde tu API acortar url express cobra vida. Crea el archivo principal app.js:

require('dotenv').config();
const express = require('express');
const mongoose = require('mongoose');
const cors = require('cors');
const { nanoid } = require('nanoid');
const Url = require('./models/Url');

const app = express();
app.use(express.json());
app.use(cors());

mongoose.connect(process.env.MONGO_URI)
  .then(() => console.log('MongoDB conectado'))
  .catch(err => console.error('Error de conexión:', err));

app.post('/api/shorten', async (req, res) => {
  const { originalUrl } = req.body;

  if (!originalUrl) {
    return res.status(400).json({ error: 'originalUrl es obligatorio' });
  }

  try {
    let url = await Url.findOne({ originalUrl });
    if (url) {
      return res.json({
        shortUrl: `${process.env.BASE_URL}/${url.shortId}`,
        shortId: url.shortId
      });
    }

    const shortId = nanoid(8);
    url = new Url({ originalUrl, shortId });
    await url.save();

    res.status(201).json({
      shortUrl: `${process.env.BASE_URL}/${shortId}`,
      shortId: shortId
    });
  } catch (error) {
    res.status(500).json({ error: 'Error interno del servidor' });
  }
});

app.listen(process.env.PORT, () => {
  console.log(`Servidor corriendo en ${process.env.BASE_URL}`);
});

El flujo es directo: recibes la URL original en el body de la petición, verificas si ya existe en la base de datos, y si no, generas un identificador único con nanoid y guardas el registro. La respuesta incluye la URL corta lista para usar.

El método que recomendamos se llama "Framework de 3 Capas para Acortadores": capa de validación (verificar la URL), capa de generación (crear el shortId), y capa de persistencia (guardar en MongoDB). Separa estas tres responsabilidades y tu código será más mantenible.

Para probarlo, abre Postman y envía una petición POST a http://localhost:3000/api/shorten con este body:

{
  "originalUrl": "https://www.mercadolibre.com.mx/productos-ofertas"
}

La respuesta será algo como:

{
  "shortUrl": "http://localhost:3000/Vk9xR2nQ",
  "shortId": "Vk9xR2nQ"
}

Paso 4: Implementar la redirección

Un nodejs acortador url rest no está completo sin la redirección. Cuando alguien visita tu link corto, el servidor debe buscar el identificador en la base de datos y redirigir al destino original.

Añade esta ruta a tu app.js, antes de app.listen:

app.get('/:shortId', async (req, res) => {
  const { shortId } = req.params;

  try {
    const url = await Url.findOne({ shortId });
    if (!url) {
      return res.status(404).json({ error: 'URL no encontrada' });
    }

    url.clicks += 1;
    await url.save();

    res.redirect(url.originalUrl);
  } catch (error) {
    res.status(500).json({ error: 'Error interno del servidor' });
  }
});

Cada vez que alguien hace clic en el link corto, incrementas el contador de clicks y luego rediriges. Así de simple. Si el identificador no existe, devuelves un 404.

La redirección HTTP 302 (Found) es la más usada en acortadores de URL porque preserva el SEO del destino original y permite tracking en tiempo real sin caching permanente del navegador.

Cómo manejar errores y validación de URLs en tu API

Tu API debe validar que la URL recibida sea válida antes de procesarla. Un enlace malformado puede causar redirecciones rotas o errores inesperados. Usa el módulo nativo URL de Node.js para validar.

Añade esta función de validación antes del endpoint /api/shorten:

function isValidUrl(string) {
  try {
    new URL(string);
    return true;
  } catch (_) {
    return false;
  }
}

Luego úsala dentro del handler:

if (!originalUrl || !isValidUrl(originalUrl)) {
  return res.status(400).json({ error: 'URL inválida o faltante' });
}

Esto previene que tu API procese cadenas como "hola" o "ftp://algo". Define qué esquemas aceptas (http, https) según tus necesidades.

Agregar parámetros UTM y tracking avanzado

Si tu API va a servir a equipos de marketing, necesitas soporte para UTM. Los parámetros UTM permiten identificar la fuente, el medio y la campaña de cada link. Esto es clave para medir tráfico desde WhatsApp en México, Instagram en Colombia o TikTok en Argentina.

Modifica tu modelo para incluir campos opcionales de UTM:

const urlSchema = new mongoose.Schema({
  originalUrl: { type: String, required: true },
  shortId: { type: String, required: true, unique: true },
  utmSource: { type: String, default: '' },
  utmMedium: { type: String, default: '' },
  utmCampaign: { type: String, default: '' },
  createdAt: { type: Date, default: Date.now },
  clicks: { type: Number, default: 0 }
});

Actualiza el endpoint /api/shorten para recibir y guardar estos parámetros:

const { originalUrl, utmSource, utmMedium, utmCampaign } = req.body;

PORT=3000
MONGO_URI=mongodb+srv://usuario:[email protected]/acortador
BASE_URL=https://api.tudominio.com

npm install --save-dev jest supertest

const request = require('supertest');
const app = require('../app');

describe('API Acortador de URL', () => {
  test('POST /api/shorten crea un link corto', async () => {
    const res = await request(app)
      .post('/api/shorten')
      .send({ originalUrl: 'https://www.mercadolibre.com.ar' });
    
    expect(res.status).toBe(201);
    expect(res.body).toHaveProperty('shortUrl');
    expect(res.body).toHaveProperty('shortId');
  });

  test('POST /api/shorten rechaza URL inválida', async () => {
    const res = await request(app)
      .post('/api/shorten')
      .send({ originalUrl: 'no-es-una-url' });
    
    expect(res.status).toBe(400);
  });

  test('GET /:shortId redirige a la URL original', async () => {
    const create = await request(app)
      .post('/api/shorten')
      .send({ originalUrl: 'https://www.instagram.com' });
    
    const res = await request(app)
      .get(`/${create.body.shortId}`);
    
    expect(res.status).toBe(302);
  });
});