📚 API REST con Node.js, Express y MongoDB - Guía Educativa

🎯 Propósito del Proyecto

Este proyecto es una API REST completa diseñada específicamente para campistas y programadores principiantes que quieren aprender desarrollo backend con Node.js. Incluye:

• ✅ Backend completo con Node.js y Express
• ✅ Base de datos MongoDB con Mongoose
• ✅ Frontend básico con HTML, CSS y JavaScript vanilla
• ✅ Operaciones CRUD completas (Crear, Leer, Actualizar, Eliminar)
• ✅ Comentarios educativos en cada archivo
• ✅ Buenas prácticas de desarrollo

---

🏗️ Arquitectura del Proyecto

api-vercel/
├── 📁 api/
│   └── index.js          # Configuración principal de Express
├── 📁 config/
│   └── db.js             # Configuración de MongoDB
├── 📁 controllers/
│   ├── userController.js # Lógica de negocio para usuarios
│   └── productController.js # Lógica de negocio para productos
├── 📁 models/
│   ├── User.js           # Esquema de usuarios
│   └── Product.js        # Esquema de productos
├── 📁 routes/
│   ├── userRoutes.js     # Rutas de usuarios
│   └── productRoutes.js  # Rutas de productos
├── 📁 public/
│   ├── index.html        # Página de gestión de usuarios
│   ├── products.html     # Página de gestión de productos
│   ├── script.js         # JavaScript para usuarios
│   ├── products.js       # JavaScript para productos
│   ├── styles.css        # Estilos generales
│   └── products.css      # Estilos específicos
├── server.js             # Punto de entrada del servidor
├── package.json          # Dependencias y scripts
└── vercel.json           # Configuración para despliegue

---

🛠️ Tecnologías Utilizadas

Backend

• Node.js: Entorno de ejecución de JavaScript en el servidor
• Express.js: Framework web minimalista y flexible
• MongoDB: Base de datos NoSQL orientada a documentos
• Mongoose: ODM (Object Document Mapper) para MongoDB
• dotenv: Manejo de variables de entorno
• CORS: Middleware para Cross-Origin Resource Sharing

Frontend

• HTML5: Estructura semántica de las páginas
• CSS3: Estilos y diseño responsive
• JavaScript ES6+: Interactividad y comunicación con la API
• Fetch API: Peticiones HTTP asíncronas

---

🚀 Instalación y Configuración

Prerrequisitos

• Node.js (versión 14 o superior)
• MongoDB (local o MongoDB Atlas)
• Editor de código (VS Code recomendado)

Pasos de Instalación

1. Clonar el repositorio

   git clone <url-del-repositorio>
   cd api-vercel

2. Instalar dependencias

   npm install

3. Configurar variables de entorno

   Crear archivo .env en la raíz del proyecto:

   MONGODB_URL=mongodb://localhost:27017/tu-base-de-datos
   PORT=5000

4. Iniciar el servidor

   # Desarrollo (con nodemon)
   npm run dev
   
   # Producción
   npm start

5. Acceder a la aplicación

   • API: http://localhost:5000
   • Frontend: http://localhost:5000/index.html

---

📖 Conceptos Clave para Principiantes

1. ¿Qué es una API REST?

Una API REST (Representational State Transfer) es un conjunto de reglas para crear servicios web que permiten la comunicación entre diferentes aplicaciones.

Características principales:

• Stateless: Cada petición es independiente
• Métodos HTTP: GET, POST, PUT, DELETE
• Recursos: Entidades como usuarios, productos
• JSON: Formato de intercambio de datos

2. Patrón MVC (Model-View-Controller)

Este proyecto implementa una variación del patrón MVC:

• Model (models/): Define la estructura de datos
• View (public/): Interfaz de usuario (HTML/CSS/JS)
• Controller (controllers/): Lógica de negocio

3. Operaciones CRUD

Cada recurso (usuarios, productos) implementa las 4 operaciones básicas:

Operación	Método HTTP	Endpoint	Descripción
Create	POST	/api/users	Crear nuevo usuario
Read	GET	/api/users	Obtener todos los usuarios
Read	GET	/api/users/:id	Obtener usuario específico
Update	PUT	/api/users/:id	Actualizar usuario
Delete	DELETE	/api/users/:id	Eliminar usuario

---

🔍 Estructura de Archivos Explicada

Backend

server.js - Punto de Entrada

// Archivo principal que inicia el servidor
// - Configura variables de entorno
// - Importa la aplicación Express
// - Define el puerto y arranca el servidor

api/index.js - Configuración de Express

// Configuración central de la aplicación
// - Middleware (CORS, JSON parsing)
// - Conexión a base de datos
// - Montaje de rutas
// - Servir archivos estáticos

models/ - Esquemas de Datos

// Definición de la estructura de datos
// - User.js: nombre, email, celular, avatar
// - Product.js: name, description, price, inStock
// - Validaciones y tipos de datos

controllers/ - Lógica de Negocio

// Funciones que manejan las peticiones
// - Interactúan con la base de datos
// - Procesan datos de entrada
// - Envían respuestas al cliente

routes/ - Definición de Endpoints

// Mapeo de URLs a funciones controladoras
// - Métodos HTTP (GET, POST, PUT, DELETE)
// - Parámetros de ruta (:id)
// - Middleware específico

Frontend

HTML - Estructura

• Semántica: Uso correcto de etiquetas HTML5
• Formularios: Validación HTML5 integrada
• Accesibilidad: Labels, alt text, estructura clara

CSS - Presentación

• Variables CSS: Colores y valores reutilizables
• Flexbox: Layout moderno y responsive
• Mobile-first: Diseño adaptable a dispositivos

JavaScript - Interactividad

• ES6+: Sintaxis moderna (const, let, arrow functions)
• Async/Await: Manejo de operaciones asíncronas
• DOM Manipulation: Actualización dinámica del contenido
• Fetch API: Comunicación con el backend

---

🎓 Flujo de Aprendizaje Recomendado

Nivel 1: Fundamentos

1. Explorar el frontend (public/)

   • Abrir index.html en el navegador
   • Inspeccionar el código HTML
   • Entender la estructura CSS
   • Seguir el flujo de JavaScript

2. Entender la API

   • Revisar server.js y api/index.js
   • Comprender el concepto de middleware
   • Explorar las rutas en routes/

Nivel 2: Base de Datos

3. Modelos de datos

   • Estudiar models/User.js y models/Product.js
   • Entender esquemas y validaciones
   • Aprender sobre MongoDB y Mongoose

4. Conexión a BD

   • Revisar config/db.js
   • Configurar MongoDB local o Atlas
   • Entender variables de entorno

Nivel 3: Lógica de Negocio

5. Controladores

   • Analizar controllers/userController.js
   • Comparar con controllers/productController.js
   • Entender operaciones CRUD

6. Integración Frontend-Backend

   • Seguir una petición completa
   • Desde el click en el frontend
   • Hasta la respuesta de la base de datos

---

🧪 Probando la API

Con el Frontend Incluido

1. Abrir http://localhost:5000/index.html
2. Crear, editar y eliminar usuarios
3. Navegar a http://localhost:5000/products.html
4. Gestionar productos

Con Herramientas Externas

Usando cURL

# Obtener todos los usuarios
curl http://localhost:5000/api/users

# Crear un nuevo usuario
curl -X POST http://localhost:5000/api/users \
  -H "Content-Type: application/json" \
  -d '{"nombre":"Juan Pérez","email":"juan@email.com","celular":"555-1234"}'

# Obtener usuario específico
curl http://localhost:5000/api/users/ID_DEL_USUARIO

# Actualizar usuario
curl -X PUT http://localhost:5000/api/users/ID_DEL_USUARIO \
  -H "Content-Type: application/json" \
  -d '{"nombre":"Juan Carlos Pérez"}'

# Eliminar usuario
curl -X DELETE http://localhost:5000/api/users/ID_DEL_USUARIO

Usando Postman

1. Crear nueva colección "API Usuarios"
2. Agregar requests para cada endpoint
3. Configurar headers: Content-Type: application/json
4. Probar todas las operaciones CRUD

---

🔧 Personalización y Extensión

Agregar Nuevos Campos

1. Modificar el modelo (models/User.js)
2. Actualizar el controlador (controllers/userController.js)
3. Modificar el frontend (public/index.html, public/script.js)

Crear Nuevos Recursos

1. Crear modelo (models/NuevoRecurso.js)
2. Crear controlador (controllers/nuevoRecursoController.js)
3. Crear rutas (routes/nuevoRecursoRoutes.js)
4. Montar rutas en api/index.js
5. Crear frontend si es necesario

Agregar Validaciones

// En el modelo
campo: {
    type: String,
    required: true,
    minlength: 3,
    maxlength: 50,
    validate: {
        validator: function(v) {
            return /regex-pattern/.test(v);
        },
        message: 'Mensaje de error personalizado'
    }
}

---

🚀 Despliegue

Vercel (Recomendado)

1. Instalar Vercel CLI: npm i -g vercel
2. Ejecutar: vercel
3. Configurar variables de entorno en el dashboard
4. El archivo vercel.json ya está configurado

Otras Opciones

• Heroku: Platform-as-a-Service popular
• Railway: Alternativa moderna a Heroku
• DigitalOcean: VPS con más control
• AWS/Azure/GCP: Servicios en la nube

---

🐛 Solución de Problemas Comunes

Error: "Cannot connect to MongoDB"

• ✅ Verificar que MongoDB esté ejecutándose
• ✅ Revisar la variable MONGODB_URL en .env
• ✅ Comprobar permisos de red (firewall)

Error: "Port already in use"

• ✅ Cambiar el puerto en .env
• ✅ Matar procesos que usen el puerto: lsof -ti:5000 | xargs kill

Error: "Module not found"

• ✅ Ejecutar npm install
• ✅ Verificar que todas las dependencias estén instaladas

Frontend no carga datos

• ✅ Verificar que el servidor esté ejecutándose
• ✅ Abrir DevTools y revisar errores en Console
• ✅ Comprobar que las URLs de la API sean correctas

---

📚 Recursos Adicionales para Aprender

Documentación Oficial

• Node.js
• Express.js
• MongoDB
• Mongoose

Tutoriales Recomendados

• MDN Web Docs - JavaScript
• freeCodeCamp - Backend Development
• The Odin Project - Full Stack JavaScript

Herramientas Útiles

• Postman: Testing de APIs
• MongoDB Compass: GUI para MongoDB
• VS Code Extensions: ES6 Snippets, REST Client
• Chrome DevTools: Debugging frontend

---

🤝 Contribuciones

Este proyecto está diseñado para aprendizaje. Si encuentras errores o tienes sugerencias:

1. Fork el repositorio
2. Crea una rama para tu feature
3. Commit tus cambios
4. Push a la rama
5. Abre un Pull Request

---

📄 Licencia

Este proyecto está bajo la Licencia ISC - ver el archivo package.json para más detalles.

---

🎉 ¡Felicitaciones!

Si has llegado hasta aquí, ya tienes una base sólida para entender:

• ✅ APIs REST y su funcionamiento
• ✅ Node.js y Express para backend
• ✅ MongoDB y Mongoose para bases de datos
• ✅ Frontend moderno con JavaScript
• ✅ Integración completa frontend-backend

Próximos Pasos Sugeridos:

1. Autenticación: JWT, sessions, OAuth
2. Validación avanzada: Joi, express-validator
3. Testing: Jest, Mocha, Supertest
4. Seguridad: Helmet, rate limiting
5. Documentación: Swagger/OpenAPI
6. Frameworks frontend: React, Vue, Angular

¡Sigue practicando y construyendo proyectos increíbles! 🚀