🏆 2.13 · Proyecto integrador: tu primera API FullStack profesional

🎯 Objetivo del tema

🗺️ Mapa del tema

Este NO es un tema teórico: es un PROYECTO integrador que demuestra que dominas el backend moderno. Combinarás TODAS las habilidades del Capítulo 2: Express, MongoDB o PostgreSQL, JWT, validaciones, RLS, deploy, monitoreo, buenas prácticas. El resultado será una API que cualquier empresa moderna reconocer como 'production-ready'. Es la pieza que te diferencia de un junior que solo hizo tutoriales.

2.13.1 Fase 1: Diseño y planificación

Antes de escribir código, planifica. Decide el stack, los endpoints, el schema de BD, y documenta todo en un archivo DECISIONES.md. Esto te ahorra reescrituras a mitad de camino y demuestra pensamiento estructurado.

Elección del proyecto: tu primera decisión

Elige una app que te interese genuinamente. Algunas ideas: biblioteca de películas, gestor de tareas, red social de libros, app de recetas, blog con comentarios, e-commerce simple. Lo importante es que tengas al menos 2-3 entidades relacionadas (ej: usuarios + posts + comentarios), para que el CRUD y las relaciones sean reales.

Stack recomendado

2.13.2 Fase 2: Setup del proyecto y conexión a BD

El primer paso técnico: crear la estructura del proyecto, instalar dependencias, configurar variables de entorno, y conectar a la BD. Es el equivalente de preparar el taller antes de empezar a construir.

Estructura recomendada del proyecto

mi-proyecto-fullstack/
├── .env              # variables de entorno (NO subir a Git)
├── .env.example      # plantilla con placeholders (SÍ subir)
├── .gitignore       # .env, node_modules, etc.
├── package.json     # dependencias y scripts
├── README.md        # documentación principal
├── DECISIONES.md    # decisiones de diseño
├── server.js        # punto de entrada
├── src/
│   ├── config/      # configuración (db, etc.)
│   ├── models/       # modelos de Mongoose / Prisma
│   ├── routes/       # rutas de la API
│   ├── controllers/  # lógica de negocio (opcional, o dentro de routes)
│   ├── middleware/   # auth, errores, etc.
│   ├── utils/         # helpers (asyncHandler, validators)
│   └── jobs/         # tareas programadas (opcional)
├── tests/            # tests (opcional pero recomendado)
└── docs/             # documentación extra

Estructura de carpetas profesional

Configuración de conexión (server.js + db.js)

// .env (NO subir a Git)
PORT=3000
NODE_ENV=development
MONGODB_URI=mongodb+srv://user:pass@cluster.mongodb.net/mi_app
JWT_SECRET=este_es_un_secret_largo_y_aleatorio_de_32_caracteres_min
JWT_REFRESH_SECRET=otro_secret_diferente_tambien_de_32_caracteres_min
SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0

// db.js: conexión a MongoDB con pool
import mongoose from 'mongoose';

const conectarDB = async () => {
  try {
    await mongoose.connect(process.env.MONGODB_URI);
    console.log('MongoDB conectado');
  } catch (error) {
    console.error('Error de conexión:', error.message);
    process.exit(1);
  }
};

export default conectarDB;

// server.js: punto de entrada
import express from 'express';
import * as Sentry from '@sentry/node';
import conectarDB from './src/config/db.js';
import authRoutes from './src/routes/auth.js';
import recursoRoutes from './src/routes/recurso.js';
import { errorHandler } from './src/middleware/errorHandler.js';

Sentry.init({ dsn: process.env.SENTRY_DSN });

const app = express();
app.use(express.json());
app.use(Sentry.Handlers.requestHandler);

// Rutas
app.use('/api/auth', authRoutes);
app.use('/api/recurso', recursoRoutes);

// Health check (para UptimeRobot)
app.get('/health', (req, res) => res.json({ status: 'ok' }));

// Errores
app.use(Sentry.Handlers.errorHandler());
app.use(errorHandler);

conectarDB().then(() => {
  const PORT = process.env.PORT || 3000;
  app.listen(PORT, () => console.log(`Servidor en puerto ${PORT}`));
});

Setup completo: server.js + db.js + Sentry

2.13.3 Fase 3: Modelos y validaciones

Los modelos definen la estructura de tus datos. Son la base de toda la app. Invertir tiempo en diseñarlos bien (con validación robusta y las relaciones correctas) te ahorra meses de bugs después.

// models/Recurso.js: ejemplo de modelo con validación completa
import mongoose from 'mongoose';

const recursoSchema = new mongoose.Schema({
  titulo: {
    type: String,
    required: [true, 'El título es obligatorio'],
    trim: true,
    minlength: [3, 'Mínimo 3 caracteres'],
    maxlength: [200, 'Máximo 200 caracteres'],
  },
  descripcion: {
    type: String,
    required: [true, 'La descripción es obligatoria'],
    trim: true,
    maxlength: [2000, 'Máximo 2000 caracteres'],
  },
  categoria: {
    type: String,
    required: true,
    enum: {
      values: ['tech', 'lifestyle', 'educacion', 'entretenimiento'],
      message: '{VALUE} no es una categoría válida',
    },
  },
  tags: {
    type: [String],
    default: [],
  },
  autor: {
    type: mongoose.Schema.Types.ObjectId,
    ref: 'Usuario',
    required: true,
  },
  publicado: {
    type: Boolean,
    default: true,
  },
  visitas: {
    type: Number,
    default: 0,
  },
}, { timestamps: true });  // crea creadoEn y actualizadoEn automáticamente

// Índices para queries frecuentes
recursoSchema.index({ categoria: 1, creadoEn: -1 });
recursoSchema.index({ titulo: 'text', descripcion: 'text' });

// Método virtual (no se guarda en la BD)
recursoSchema.virtual('resumen').get(function() {
  return `${this.titulo} - ${this.descripcion.substring(0, 100)}...`;
});

export const Recurso = mongoose.model('Recurso', recursoSchema);

Modelo Mongoose con validación completa

2.13.4 Fase 4: Autenticación JWT completa

Tu API necesita saber QUIÉN hace cada petición. JWT con bcrypt es el estándar. Implementa register, login, refresh, logout, y middlewares de autenticación y autorización por roles.

Checklist de auth que tu app debe tener

• ✓ POST /api/auth/register con bcrypt.hash(password, 12)
• ✓ POST /api/auth/login con bcrypt.compare() y emisión de JWT
• ✓ POST /api/auth/refresh con refresh token en cookie httpOnly
• ✓ POST /api/auth/logout que limpia la cookie
• ✓ Middleware authMiddleware que verifica el JWT y añade req.user
• ✓ Middleware adminMiddleware (opcional) para rutas solo-admin
• ✓ Variables JWT_SECRET y JWT_REFRESH_SECRET únicas y largas (32+ chars)
• ✓ Códigos HTTP correctos: 401 (no autenticado), 403 (no autorizado), 201 (creado), 200 (OK), 204 (sin contenido)
• ✓ Mensajes genéricos: 'Credenciales inválidas' en login (no 'Email no existe' vs 'Contraseña incorrecta')

2.13.5 Fase 5: CRUD + búsqueda + paginación

El corazón de tu API: las rutas que permiten a los usuarios interactuar con los datos. CRUD (Create, Read, Update, Delete) + búsqueda + paginación es el 80% de lo que cualquier app necesita.

Checklist de rutas que tu app debe tener

• ✓ GET /api/recurso - listar paginado (con ?page y ?limit)
• ✓ GET /api/recurso/:id - ver detalle de un recurso
• ✓ POST /api/recurso - crear (protegido con auth)
• ✓ PUT /api/recurso/:id - actualizar (protegido, solo el autor)
• ✓ DELETE /api/recurso/:id - eliminar (protegido, solo el autor o admin)
• ✓ GET /api/recurso/buscar?q=termino - búsqueda por texto
• ✓ GET /api/recurso/categoria/:cat - filtrar por categoría
• ✓ GET /api/recurso/mios - listar solo los del usuario actual
• ✓ Validación en TODAS las rutas POST/PUT
• ✓ Códigos HTTP correctos en TODAS las respuestas

2.13.6 Fase 6: Deploy + monitoreo + documentación

Tu código está listo, pero si no está en internet y monitoreado, no es una app real. La última fase: deploy en Railway, configurar Sentry para tracking de errores, UptimeRobot para uptime 24/7, y escribir un README.md que un reclutador pueda leer en 2 minutos.

El README.md profesional

# 📚 Mi Red Social de Libros

API REST para gestionar libros, reseñas y listas de lectura.
Construida con Node.js, Express, MongoDB Atlas, y JWT.

## 🚀 Demo en vivo
https://mi-api.railway.app

## ✨ Características
- Auth con JWT (registro, login, refresh tokens)
- CRUD completo de libros, reseñas, listas
- Búsqueda por texto y filtros por categoría
- Paginación y ordenamiento
- Tracking de errores con Sentry
- Uptime 24/7 con UptimeRobot
- HTTPS automático
- Documentación con OpenAPI/Swagger

## 🛠️ Stack
- **Backend**: Node.js 20, Express 4
- **BD**: MongoDB Atlas (M0 gratis)
- **Auth**: JWT con bcrypt (12 rounds)
- **Deploy**: Railway
- **Monitoreo**: Sentry + UptimeRobot
- **Validación**: Mongoose validators + express-validator

## 📚 Documentación API
Visita `/api-docs` para la documentación interactiva con Swagger.

## 🏃 Correr localmente
```bash
git clone https://github.com/tu-usuario/mi-proyecto.git
cd mi-proyecto
npm install
cp .env.example .env  # llenar con tus credenciales
npm run dev
```

## 🧪 Tests
```bash
npm test
```

## 📝 Licencia
MIT

## 👤 Autor
Tu Nombre - [LinkedIn](https://linkedin.com/in/tu-usuario) - tu@correo.com

README.md profesional

📚 Contenido ampliado

Material adicional, referencias externas verificadas y ejemplos extendidos.