EndpointsDeLaAPI - JesusAraujoDEV/mediart GitHub Wiki

Documentación de la API Mediart

La API de Mediart es el punto de acceso central para todas las funcionalidades de la plataforma, diseñada con principios RESTful para una comunicación clara, predecible y sin estado. Cada endpoint está meticulosamente definido para gestionar recursos específicos y facilitar una interacción fluida con el ecosistema multimedia de Mediart.

1. Autenticación (/api/auth)

El módulo de autenticación es la puerta de entrada a Mediart, gestionando de forma segura el acceso de los usuarios a la plataforma.

  • POST /api/auth/login

    • Propósito: Permite a un usuario autenticarse en Mediart utilizando sus credenciales (email y contraseña).
    • Mecanismo: Internamente, utiliza la estrategia local de Passport.js para verificar el email y el hash de la contraseña contra los registros en la base de datos. Si las credenciales son válidas, se genera un JSON Web Token (JWT).
    • Cuerpo de la Solicitud (Body):
      • email (string, requerido): La dirección de correo electrónico del usuario.
      • password (string, requerido): La contraseña del usuario.
    • Respuesta Exitosa (200 OK):
      • Un objeto JSON que contiene el JWT (generalmente como un access_token o token) que debe ser incluido en las cabeceras Authorization: Bearer <token> de futuras solicitudes a rutas protegidas.
      • Los datos básicos del usuario autenticado (ej., id, username, email, profilePictureUrl), útiles para inicializar la sesión en el cliente.
    • Posibles Respuestas de Error (4xx):
      • 400 Bad Request: Si el formato del email o la contraseña es inválido (validación Joi).
      • 401 Unauthorized: Si las credenciales son incorrectas.

  • POST /api/auth/recovery

    • Propósito: Inicia el proceso de recuperación de contraseña, enviando un enlace o código único al correo electrónico del usuario.
    • Mecanismo: Verifica la existencia del email en la base de datos. Si existe, genera un token de recuperación de un solo uso con un tiempo de expiración limitado y lo envía al usuario por correo electrónico utilizando Nodemailer.
    • Cuerpo de la Solicitud (Body):
      • email (string, requerido): La dirección de correo electrónico del usuario que olvidó su contraseña.
    • Respuesta Exitosa (200 OK):
      • Un mensaje indicando que, si el correo electrónico existe en el sistema, se ha enviado un enlace/código de recuperación. La respuesta es intencionalmente genérica para evitar la enumeración de usuarios.
    • Posibles Respuestas de Error (4xx):
      • 400 Bad Request: Si el formato del email es inválido.
      • 500 Internal Server Error: Si hay un problema con el servicio de envío de correo.

  • POST /api/auth/change-password

    • Propósito: Permite a un usuario restablecer su contraseña utilizando un token de recuperación previamente enviado.
    • Mecanismo: Valida la existencia y la validez del token de recuperación. Si el token es válido y no ha expirado, permite al usuario establecer una newPassword, la cual es hasheada y actualizada en la base de datos. El token se invalida tras su uso.
    • Cuerpo de la Solicitud (Body):
      • token (string, requerido): El token de recuperación recibido por correo electrónico.
      • newPassword (string, requerido): La nueva contraseña que el usuario desea establecer. Deberá cumplir con las políticas de complejidad (validación Joi).
    • Respuesta Exitosa (200 OK):
      • Un mensaje de confirmación de que la contraseña ha sido cambiada exitosamente.
    • Posibles Respuestas de Error (4xx):
      • 400 Bad Request: Si el token no es válido o la nueva contraseña no cumple con los requisitos.
      • 401 Unauthorized: Si el token ha expirado o ya ha sido utilizado.

2. Usuarios (/api/users)

Este conjunto de endpoints gestiona la información de los usuarios dentro de Mediart, permitiendo operaciones CRUD (Crear, Leer, Actualizar, Eliminar) sobre sus perfiles.

  • GET /api/users

    • Propósito: Recupera una lista de todos los usuarios registrados en la plataforma.
    • Autenticación: Requiere un JWT válido en la cabecera Authorization o una Master API Key (para fines administrativos o de depuración, si está implementada).
    • Parámetros de Consulta (Query):
      • query (string, opcional): Permite filtrar la lista de usuarios por un término de búsqueda (ej., por nombre de usuario, nombre real).
      • limit (number, opcional): Define el número máximo de usuarios a retornar.
      • offset (number, opcional): Define el punto de inicio para la paginación.
    • Respuesta Exitosa (200 OK):
      • Un array de objetos de usuario, cada uno con sus detalles (ej., id, username, email, profilePictureUrl, bio).
    • Posibles Respuestas de Error (4xx):
      • 401 Unauthorized: Si no se proporciona un JWT válido o Master API Key.

  • POST /api/users

    • Propósito: Registra un nuevo usuario en la plataforma Mediart.
    • Autenticación: No requiere autenticación JWT (es para registro).
    • Cuerpo de la Solicitud (Body):
      • username (string, requerido): Nombre de usuario único.
      • email (string, requerido): Correo electrónico único del usuario.
      • password (string, requerido): Contraseña del usuario (validación de complejidad con Joi).
      • firstName (string, opcional): Nombre de pila del usuario.
      • lastName (string, opcional): Apellido del usuario.
      • bio (string, opcional): Breve biografía del usuario.
      • profilePicture (file, opcional): Un archivo de imagen para la foto de perfil del usuario. Gestionado con Multer para la subida y ImgBB Uploader para el almacenamiento externo.
    • Respuesta Exitosa (201 Created):
      • Un objeto JSON con los datos del nuevo usuario (excluyendo la contraseña).
    • Posibles Respuestas de Error (4xx):
      • 400 Bad Request: Si los datos de entrada no cumplen con las validaciones (Joi), o si el email/username ya existe.
      • 409 Conflict: Si el username o email ya están registrados.

  • PATCH /api/users/:id

    • Propósito: Actualiza la información de un usuario existente.
    • Autenticación: Requiere un JWT válido. Solo el usuario autenticado (cuyo id coincida con el :id en la URL) o un usuario con Master API Key puede realizar la actualización.
    • Parámetros de Ruta (Params):
      • id (UUID, requerido): El ID único del usuario a actualizar.
    • Cuerpo de la Solicitud (Body):
      • Campos a actualizar (ej., username, email, firstName, lastName, bio).
      • profilePicture (file, opcional): Nuevo archivo de imagen para la foto de perfil.
    • Respuesta Exitosa (200 OK):
      • El objeto de usuario con los datos actualizados.
    • Posibles Respuestas de Error (4xx):
      • 400 Bad Request: Datos de actualización inválidos.
      • 401 Unauthorized: Si el JWT es inválido o el usuario no tiene permisos para actualizar este perfil.
      • 403 Forbidden: Si el usuario autenticado no es el propietario del perfil.
      • 404 Not Found: Si el usuario con el ID especificado no existe.

  • DELETE /api/users/:id

    • Propósito: Elimina un usuario de la plataforma.
    • Autenticación: Requiere un JWT válido. Solo el usuario autenticado (cuyo id coincida con el :id en la URL) o un usuario con Master API Key puede eliminar la cuenta.
    • Parámetros de Ruta (Params):
      • id (UUID, requerido): El ID único del usuario a eliminar.
    • Respuesta Exitosa (204 No Content):
      • Respuesta vacía, indicando que la operación fue exitosa.
    • Posibles Respuestas de Error (4xx):
      • 401 Unauthorized: Si el JWT es inválido.
      • 403 Forbidden: Si el usuario autenticado no es el propietario del perfil.
      • 404 Not Found: Si el usuario no existe.

  • GET /api/users/by-username/:username

    • Propósito: Recupera los detalles de un usuario específico buscando por su nombre de usuario.
    • Autenticación: No requiere JWT. Diseñado para búsquedas públicas de perfiles.
    • Parámetros de Ruta (Params):
      • username (string, requerido): El nombre de usuario único del usuario a buscar.
    • Parámetros de Consulta (Query):
      • include (string, opcional): Permite especificar relaciones a cargar (?include=playlists, ?include=followers). Útil para optimizar las consultas.
    • Respuesta Exitosa (200 OK):
      • Un objeto JSON con los detalles del usuario encontrado, incluyendo las asociaciones solicitadas.
    • Posibles Respuestas de Error (4xx):
      • 404 Not Found: Si no se encuentra un usuario con el nombre de usuario especificado.

  • GET /api/users/:id

    • Propósito: Recupera los detalles de un usuario específico buscando por su ID único.
    • Autenticación: No requiere JWT. Diseñado para búsquedas públicas de perfiles.
    • Parámetros de Ruta (Params):
      • id (UUID, requerido): El ID único del usuario a buscar.
    • Respuesta Exitosa (200 OK):
      • Un objeto JSON con los detalles del usuario encontrado.
    • Posibles Respuestas de Error (4xx):
      • 404 Not Found: Si no se encuentra un usuario con el ID especificado.

3. Playlists (/api/playlists)

Estos endpoints permiten a los usuarios crear, gestionar y colaborar en colecciones personalizadas de contenido multimedia.

  • GET /api/playlists

    • Propósito: Obtiene una lista paginada de todas las playlists que han sido marcadas como públicas.
    • Autenticación: No requiere JWT. Acceso público a playlists compartidas.
    • Parámetros de Consulta (Query):
      • limit (number, opcional): Número máximo de playlists a devolver.
      • offset (number, opcional): Punto de inicio para la paginación.
      • type (string, opcional): Filtrar por tipo de playlist (ej., music, movie).
      • userId (UUID, opcional): Filtrar playlists por un usuario específico.
    • Respuesta Exitosa (200 OK):
      • Un array de objetos de playlist, cada uno con sus detalles básicos (ID, nombre, creador, URL de portada).

  • GET /api/playlists/:playlistId

    • Propósito: Recupera todos los detalles de una playlist específica, incluyendo sus ítems.
    • Autenticación: No requiere JWT si la playlist es pública. Si la playlist es privada o colaborativa, podría requerir JWT si el usuario autenticado es el propietario o un colaborador.
    • Parámetros de Ruta (Params):
      • playlistId (UUID, requerido): El ID único de la playlist.
    • Respuesta Exitosa (200 OK):
      • Un objeto JSON completo de la playlist, incluyendo un array anidado de sus ítems multimedia.
    • Posibles Respuestas de Error (4xx):
      • 404 Not Found: Si la playlist no existe.
      • 403 Forbidden: Si la playlist es privada y el usuario no está autorizado a verla.

  • POST /api/playlists

    • Propósito: Crea una nueva playlist para el usuario autenticado.
    • Autenticación: Requiere JWT.
    • Cuerpo de la Solicitud (Body):
      • name (string, requerido): Nombre de la playlist.
      • description (string, opcional): Descripción de la playlist.
      • isPublic (boolean, opcional, por defecto true): Indica si la playlist es pública o privada.
      • isCollaborative (boolean, opcional, por defecto false): Indica si la playlist permite colaboradores.
      • playlistCover (file, opcional): Un archivo de imagen para la portada de la playlist. Gestionado con Multer y ImgBB Uploader.
    • Respuesta Exitosa (201 Created):
      • El objeto JSON de la playlist recién creada.

  • PATCH /api/playlists/:playlistId

    • Propósito: Actualiza los metadatos de una playlist existente (nombre, descripción, visibilidad, colaboración).
    • Autenticación: Requiere JWT. Solo el propietario de la playlist puede realizar esta operación.
    • Parámetros de Ruta (Params):
      • playlistId (UUID, requerido).
    • Cuerpo de la Solicitud (Body):
      • Campos a actualizar (ej., name, description, isPublic, isCollaborative).
      • playlistCover (file, opcional): Nuevo archivo de imagen para la portada.
    • Respuesta Exitosa (200 OK):
      • El objeto de la playlist con los datos actualizados.

  • DELETE /api/playlists/:playlistId

    • Propósito: Elimina una playlist.
    • Autenticación: Requiere JWT. Solo el propietario de la playlist puede realizar esta operación.
    • Parámetros de Ruta (Params):
      • playlistId (UUID, requerido).
    • Respuesta Exitosa (204 No Content):
      • Respuesta vacía.

  • POST /api/playlists/:playlistId/items

    • Propósito: Agrega uno o varios ítems multimedia a una playlist específica.
    • Autenticación: Requiere JWT. Solo el dueño de la playlist o un colaborador puede agregar ítems.
    • Parámetros de Ruta (Params):
      • playlistId (UUID, requerido).
    • Cuerpo de la Solicitud (Body):
      • itemIds (array de UUIDs, opcional): Un array de IDs de ítems multimedia ya existentes en la base de datos de Mediart.
      • items (array de objetos, opcional): Un array de objetos, donde cada objeto representa un nuevo ítem multimedia con sus datos (ej., { title, type, externalId, source }). La API intentará crear estos ítems si no existen y luego los asociará.
      • Se espera al menos uno de itemIds o items.
    • Respuesta Exitosa (200 OK):
      • La playlist actualizada con los nuevos ítems.

  • DELETE /api/playlists/:playlistId/items/:itemId

    • Propósito: Elimina un ítem multimedia específico de una playlist.
    • Autenticación: Requiere JWT. Solo el dueño de la playlist o un colaborador puede eliminar ítems.
    • Parámetros de Ruta (Params):
      • playlistId (UUID, requerido).
      • itemId (UUID, requerido): El ID del ítem multimedia a eliminar de la playlist.
    • Respuesta Exitosa (204 No Content):
      • Respuesta vacía.

  • POST /api/playlists/:playlistId/collaborators

    • Propósito: Agrega uno o varios usuarios como colaboradores a una playlist colaborativa.
    • Autenticación: Requiere JWT. Solo el dueño de la playlist puede agregar colaboradores. La playlist debe estar marcada como isCollaborative: true.
    • Parámetros de Ruta (Params):
      • playlistId (UUID, requerido).
    • Cuerpo de la Solicitud (Body):
      • userId (UUID, opcional): El ID de un solo usuario a agregar como colaborador.
      • userIds (array de UUIDs, opcional): Un array de IDs de usuarios a agregar como colaboradores.
      • Se espera al menos uno de userId o userIds.
    • Respuesta Exitosa (200 OK):
      • La playlist actualizada, mostrando la lista de colaboradores.
    • Posibles Respuestas de Error (4xx):
      • 400 Bad Request: Si la playlist no es colaborativa o el formato del ID de usuario es incorrecto.
      • 404 Not Found: Si la playlist o algún usuario a agregar no existe.
      • 403 Forbidden: Si el usuario autenticado no es el dueño de la playlist.

  • PATCH /api/playlists/:playlistId/collaborators/remove

    • Propósito: Elimina uno o varios usuarios de la lista de colaboradores de una playlist.
    • Autenticación: Requiere JWT. Solo el dueño de la playlist puede eliminar colaboradores.
    • Parámetros de Ruta (Params):
      • playlistId (UUID, requerido).
    • Cuerpo de la Solicitud (Body):
      • userId (UUID, opcional): El ID de un solo usuario a eliminar como colaborador.
      • userIds (array de UUIDs, opcional): Un array de IDs de usuarios a eliminar como colaboradores.
      • Se espera al menos uno de userId o userIds.
    • Respuesta Exitosa (200 OK):
      • La playlist actualizada, mostrando la nueva lista de colaboradores.
    • Posibles Respuestas de Error (4xx):
      • 400 Bad Request: Si el formato del ID de usuario es incorrecto.
      • 404 Not Found: Si la playlist o algún usuario a eliminar no existe.
      • 403 Forbidden: Si el usuario autenticado no es el dueño de la playlist.

4. Ítems Multimedia (/api/items)

Estos endpoints gestionan la base de datos interna de ítems multimedia de Mediart. Aunque gran parte del contenido proviene de APIs externas, Mediart mantiene un registro propio para asociarlos a playlists y recomendaciones.

  • GET /api/items

    • Propósito: Lista todos los ítems multimedia (películas, canciones, libros, videojuegos) que han sido registrados en la base de datos interna de Mediart.
    • Autenticación: Opcional. Podría ser de acceso público o requerir JWT para listas más extensas.
    • Parámetros de Consulta (Query):
      • limit, offset: Para paginación.
      • type (string, opcional): Filtrar por tipo de ítem (ej., movie, song, book, videogame).
      • title (string, opcional): Filtrar por título.
    • Respuesta Exitosa (200 OK):
      • Un array de objetos de ítems multimedia.

  • GET /api/items/:itemId

    • Propósito: Obtiene los detalles completos de un ítem multimedia específico por su ID interno.
    • Autenticación: Opcional (generalmente público).
    • Parámetros de Ruta (Params):
      • itemId (UUID, requerido): El ID único del ítem.
    • Respuesta Exitosa (200 OK):
      • Un objeto JSON con todos los detalles del ítem (ej., título, descripción, tipo, enlaces externos, URL de portada).

  • POST /api/items

    • Propósito: Crea un nuevo registro de ítem multimedia en la base de datos de Mediart. Esto suele ocurrir cuando un ítem es agregado a una playlist por primera vez, o si es un ítem totalmente personalizado.
    • Autenticación: Requiere JWT. Puede estar restringido a usuarios con ciertos permisos.
    • Cuerpo de la Solicitud (Body):
      • title (string, requerido): Título del ítem.
      • type (enum string, requerido): Tipo de contenido (ej., movie, tvshow, song, artist, album, videogame, book).
      • externalId (string, opcional): ID del ítem en la fuente externa (ej., ID de Spotify, ID de TMDB). Útil para relacionar con datos externos.
      • source (string, opcional): Nombre de la fuente externa (ej., Spotify, TMDB).
      • Otros campos relevantes según el tipo (ej., releaseDate, duration, genres, authors, platforms).
    • Respuesta Exitosa (201 Created):
      • El objeto JSON del ítem multimedia recién creado.

  • PATCH /api/items/:itemId

    • Propósito: Actualiza la información de un ítem multimedia existente.
    • Autenticación: Requiere JWT. Restringido a administradores o usuarios con permisos específicos.
    • Parámetros de Ruta (Params):
      • itemId (UUID, requerido).
    • Cuerpo de la Solicitud (Body):
      • Campos a actualizar (ej., title, description, imageUrl).
    • Respuesta Exitosa (200 OK):
      • El objeto del ítem con los datos actualizados.

  • DELETE /api/items/:itemId

    • Propósito: Elimina un ítem multimedia de la base de datos interna.
    • Autenticación: Requiere JWT. Restringido a administradores o usuarios con permisos específicos.
    • Parámetros de Ruta (Params):
      • itemId (UUID, requerido).
    • Respuesta Exitosa (204 No Content):
      • Respuesta vacía.

5. Búsqueda (/api/search)

Este módulo proporciona capacidades de búsqueda avanzada, consolidando resultados de múltiples fuentes.

  • GET /api/search

    • Propósito: Realiza una búsqueda federada de contenido multimedia en diversas fuentes externas e internas.
    • Autenticación: Requiere JWT. Esto permite a Mediart personalizar o mejorar la búsqueda basándose en el contexto del usuario.
    • Parámetros de Consulta (Query):
      • q (string, requerido): El término de búsqueda del usuario (ej., "Taylor Swift", "El Señor de los Anillos").
      • type (enum string, opcional): Permite limitar la búsqueda a un tipo específico de contenido. Valores posibles: movie, tvshow, song, artist, album, videogame, book, general. Si no se especifica, la búsqueda es general (en todas las categorías relevantes).
    • Mecanismo: El servicio de búsqueda (searchService) actúa como un agregador, haciendo llamadas simultáneas o secuenciales a las APIs externas (TMDB, Spotify, Google Books, IGDB) según el type solicitado. Consolida los resultados, normaliza su formato y los devuelve al cliente.
    • Respuesta Exitosa (200 OK):
      • Un objeto JSON con los resultados de la búsqueda, categorizados por tipo (ej., { movies: [...], songs: [...], books: [...] }).

  • GET /api/search/users

    • Propósito: Permite a los usuarios buscar otros perfiles de usuario dentro de Mediart por nombre de usuario.
    • Autenticación: Requiere JWT.
    • Parámetros de Consulta (Query):
      • q (string, requerido): El término de búsqueda para el nombre de usuario (ej., "john_doe", "ana"). La búsqueda podría ser parcial o basada en coincidencias exactas.
      • limit, offset: Para paginación de resultados.
    • Respuesta Exitosa (200 OK):
      • Un array de objetos de usuario que coinciden con el término de búsqueda, mostrando información básica como id, username, profilePictureUrl.

6. Recomendaciones (/api/recommendations)

Estos endpoints son el escaparate de la inteligencia de Mediart, ofreciendo sugerencias personalizadas de contenido a los usuarios.

  • POST /api/recommendations/movies
  • POST /api/recommendations/tvshows
  • POST /api/recommendations/books
  • POST /api/recommendations/songs
  • POST /api/recommendations/artists
  • POST /api/recommendations/albums
  • POST /api/recommendations/videogames
  • POST /api/recommendations/mix
    • Propósito General: Generar recomendaciones de contenido multimedia personalizadas basadas en el tipo de contenido y en la interacción del usuario. La ruta /mix proporciona recomendaciones que pueden abarcar diferentes tipos de medios.
    • Autenticación: Requiere JWT. Las recomendaciones son personalizadas para el usuario autenticado.
    • Cuerpo de la Solicitud (Body):
      • itemName (string, opcional): Un nombre de ítem (ej., "Dune", "Bohemian Rhapsody") que puede servir como semilla o contexto para la recomendación. Si no se provee, la IA puede usar el historial y preferencias del usuario.
      • Otros campos contextuales (ej., genres, mood, keywords) podrían ser añadidos en futuras versiones.
    • Mecanismo: Los servicios de recomendación utilizan una combinación de algoritmos internos y la potencia de Google Gemini AI y DeepSeek AI. La IA procesa la entrada del usuario (itemName), su historial de actividad en Mediart (playlists, ítems vistos/leídos/escuchados) y posiblemente datos adicionales obtenidos de las APIs externas. Luego, genera una lista de ítems recomendados que se alinean con los gustos y el contexto del usuario.
    • Respuesta Exitosa (200 OK):
      • Un array de objetos de ítems multimedia recomendados, con sus detalles relevantes.
    • Posibles Respuestas de Error (5xx):
      • 500 Internal Server Error: Si hay un problema con la comunicación con los modelos de IA o con la generación de recomendaciones.

7. Perfil de Usuario (/api/profile)

Este conjunto de endpoints permite al usuario autenticado interactuar con y gestionar sus propios datos de perfil, relaciones sociales y colecciones personales.

  • GET /api/profile

    • Propósito: Recupera los detalles completos del perfil del usuario actualmente autenticado.
    • Autenticación: Requiere JWT.
    • Respuesta Exitosa (200 OK):
      • Un objeto JSON con todos los datos del usuario autenticado, incluyendo su ID, nombre de usuario, email, biografía, URL de la imagen de perfil, etc.

  • GET /api/profile/owned-playlists

    • Propósito: Lista todas las playlists que han sido creadas por el usuario autenticado.
    • Autenticación: Requiere JWT.
    • Respuesta Exitosa (200 OK):
      • Un array de objetos de playlist, conteniendo los detalles de cada playlist propiedad del usuario.

  • GET /api/profile/saved-playlists

    • Propósito: Lista todas las playlists que el usuario autenticado ha guardado en su biblioteca personal (sin ser necesariamente el creador o colaborador).
    • Autenticación: Requiere JWT.
    • Respuesta Exitosa (200 OK):
      • Un array de objetos de playlist, representando las playlists que el usuario ha marcado como "guardadas".

  • POST /api/profile/saved-playlists/:playlistId

    • Propósito: Permite al usuario autenticado guardar una playlist (que no sea suya) en su colección personal.
    • Autenticación: Requiere JWT.
    • Parámetros de Ruta (Params):
      • playlistId (UUID, requerido): El ID de la playlist a guardar.
    • Respuesta Exitosa (200 OK / 201 Created):
      • Confirmación de que la playlist ha sido guardada.

  • DELETE /api/profile/saved-playlists/:playlistId

    • Propósito: Permite al usuario autenticado eliminar una playlist guardada de su colección personal.
    • Autenticación: Requiere JWT.
    • Parámetros de Ruta (Params):
      • playlistId (UUID, requerido): El ID de la playlist a eliminar de las guardadas.
    • Respuesta Exitosa (204 No Content):
      • Respuesta vacía.

  • GET /api/profile/my-followers

    • Propósito: Lista todos los usuarios que están siguiendo al usuario autenticado.
    • Autenticación: Requiere JWT.
    • Respuesta Exitosa (200 OK):
      • Un array de objetos de usuario, representando a los seguidores.

  • GET /api/profile/my-followings

    • Propósito: Lista todos los usuarios que el usuario autenticado está siguiendo.
    • Autenticación: Requiere JWT.
    • Respuesta Exitosa (200 OK):
      • Un array de objetos de usuario, representando a los usuarios seguidos.

  • POST /api/profile/follow/:followedId

    • Propósito: Permite al usuario autenticado seguir a otro usuario.
    • Autenticación: Requiere JWT.
    • Parámetros de Ruta (Params):
      • followedId (UUID, requerido): El ID del usuario al que se desea seguir.
    • Respuesta Exitosa (200 OK):
      • Confirmación de la relación de seguimiento.

  • DELETE /api/profile/follow/:followedId

    • Propósito: Permite al usuario autenticado dejar de seguir a otro usuario.
    • Autenticación: Requiere JWT.
    • Parámetros de Ruta (Params):
      • followedId (UUID, requerido): El ID del usuario al que se desea dejar de seguir.
    • Respuesta Exitosa (204 No Content):
      • Respuesta vacía.

8. Descripción de Servicios y Lógica Subyacente

Cada conjunto de endpoints se apoya en servicios internos específicos, que encapsulan la lógica de negocio y la interacción con la base de datos y APIs externas.

  • Servicios de Usuario:

    • Manejan la complejidad detrás del registro, login (hasheo de contraseñas, generación de JWTs), procesos de recuperación y cambio de contraseña.
    • Gestionan el ciclo de vida de los perfiles de usuario, incluyendo la carga de imágenes de perfil (con Multer y ImgBB) y la administración de las relaciones de seguidores y seguidos.
    • Coordinan el guardado y eliminación de playlists en la biblioteca personal de cada usuario.

  • Servicios de Playlists:

    • Encapsulan toda la lógica para el CRUD de playlists, desde la creación con sus metadatos (públicas/privadas, colaborativas) hasta la gestión de portadas.
    • Manejan la adición y eliminación de ítems multimedia a playlists, validando permisos.
    • Son responsables de la compleja gestión de colaboradores: añadir, remover, y asegurar que solo los dueños puedan administrar la colaboración.
    • Aseguran el soporte para las playlists colaborativas, permitiendo que múltiples usuarios contribuyan a una misma lista.

  • Servicios de Ítems Multimedia:

    • Proporcionan las operaciones CRUD para los ítems multimedia en la base de datos interna de Mediart.
    • Establecen y gestionan las relaciones de los ítems con las playlists.
    • Normalizan los datos de ítems provenientes de diversas fuentes externas para mantener la coherencia interna.

  • Servicios de Búsqueda:

    • Orquestan la búsqueda avanzada paralela o secuencial en múltiples fuentes externas (TMDB, Spotify, IGDB, Google Books) y en la base de datos de usuarios de Mediart.
    • Consolidan y formatean los resultados de estas diversas APIs en una respuesta unificada y legible para el cliente.
    • Gestionan la lógica para la búsqueda específica de usuarios por nombre de usuario.

  • Servicios de Recomendación:

    • Son la columna vertebral de la inteligencia de Mediart. Reciben las solicitudes de recomendación (con o sin contexto inicial de un itemName).
    • Acceden al historial del usuario, preferencias y otros datos relevantes.
    • Envían esta información a los modelos de Inteligencia Artificial (Gemini AI, DeepSeek AI) para un procesamiento avanzado.
    • Procesan y devuelven los resultados generados por la IA al cliente, a menudo enriqueciéndolos con metadatos adicionales desde las APIs externas.

9. Notas Generales de la API

  • Autenticación: Todas las rutas marcadas como requeridas para la autenticación esperan un JSON Web Token (JWT) válido. Este token debe ser enviado en la cabecera Authorization con el prefijo Bearer (ej., Authorization: Bearer <tu_jwt_aqui>). El middleware de autenticación de Passport.js se encarga de la verificación.
  • Validación de Datos: La robustez de la API está garantizada por la exhaustiva validación de datos de entrada. Toda la validación se realiza utilizando la librería Joi, asegurando que los cuerpos de solicitud, parámetros de consulta y parámetros de ruta cumplan con los esquemas esperados antes de que la lógica de negocio sea ejecutada.
  • Manejo de Errores: El sistema cuenta con middlewares personalizados de manejo de errores que, en conjunto con la librería Boom, proporcionan respuestas de error consistentes y bien estructuradas (ej., 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error), con mensajes claros y códigos de error específicos.
  • Subida de Imágenes: La gestión de archivos de imagen (perfiles de usuario, portadas de playlists) se facilita mediante el middleware Multer en el backend. Las imágenes no se almacenan directamente en el servidor de Mediart, sino que son subidas a un servicio externo especializado, ImgBB, para una mejor escalabilidad, rendimiento y gestión de almacenamiento.
  • Documentación Interactiva (Swagger): Para una exploración y prueba sencilla de la API, una documentación interactiva completa está disponible automáticamente en la ruta /api-docs del servidor backend. Esta interfaz, generada por Swagger UI, permite a los desarrolladores visualizar cada endpoint, sus parámetros, modelos de respuesta y realizar solicitudes de prueba en tiempo real, lo que acelera el desarrollo y la integración.

Esta sección proporciona una descripción muy detallada y funcional de cada endpoint, lo que deberían hacer, y cómo se integran con las diversas capas y servicios del backend de Mediart.

© 2025 MEDIART. TODOS LOS DERECHOS RESERVADOS.

Construyendo el futuro de tu experiencia multimedia PERSONAL.

⚠️ **GitHub.com Fallback** ⚠️