Playlist Bot API v0.5

Este proyecto es una API RESTful desarrollada en Java con Spring Boot, creada como parte del curso "Desarrollo Fullstack I". El enfoque principal del proyecto es el desarrollo backend, demostrando la integración con una API externa (Spotify) y la gestión de autenticación segura mediante OAuth 2.0.

El propósito de esta API es servir como backend para un bot de chat (por ejemplo, en Twitch o YouTube). El bot escucharía los comandos de los espectadores en el chat, extraería un ID de canción de Spotify y usaría esta API para agregarla a una playlist designada.

Requisitos de Infraestructura

Para funcionar correctamente, esta aplicación necesita:

1. Java 17 o superior.
2. Maven para la gestión de dependencias.
3. Una Base de Datos SQL: La aplicación utiliza JPA para persistir los tokens de los usuarios. Puedes configurarla para usar cualquier base de datos compatible (como H2 para desarrollo, o PostgreSQL/MySQL para producción). La base de datos es crucial para guardar los refresh_token y evitar que los usuarios tengan que autorizar la aplicación repetidamente.
4. Una cuenta de Desarrollador de Spotify: Necesitarás crear una aplicación en el Dashboard de Desarrolladores de Spotify para obtener tus credenciales.

Configuración del Proyecto

La configuración de las credenciales y otros valores sensibles se gestiona a través de un archivo .env.

1. Crea un archivo llamado .env (usa el .env.template)en el directorio raíz de tu proyecto.

2. Añade las siguientes variables:

   SPOTIFY_API_ID=tu_client_id_de_spotify
   SPOTIFY_API_CLIENT=tu_client_secret_de_spotify
   SPOTIFY_API_REDIRECTURI=tu_uri_de_redireccion
   

   • SPOTIFY_API_ID: El Client ID de tu aplicación en el dashboard de Spotify.
   • SPOTIFY_API_CLIENT: El Client Secret de tu aplicación.
   • SPOTIFY_API_REDIRECTURI: La URL a la que Spotify redirigirá al usuario después de la autorización. Debe coincidir exactamente con una de las URIs que registraste en el dashboard.

Flujo de Autenticación (OAuth 2.0)

Para que la API pueda realizar acciones en nombre de un usuario, este debe autorizar la aplicación una vez.

Paso 1: Iniciar la Autorización

El usuario (o el dueño del canal de streaming) debe iniciar el proceso visitando este endpoint.

• Endpoint: GET /api/v1/auth/login
• Descripción: Al llamar a este endpoint, la API genera una URL única de autorización de Spotify. El usuario debe abrir esta URL en su navegador, iniciar sesión en Spotify y conceder los permisos solicitados.

Paso 2: El Callback de Spotify

Una vez que el usuario autoriza la aplicación, Spotify lo redirige al redirect_uri que configuraste.

• Endpoint: GET /api/v1/auth/callback
• Descripción: Este endpoint recibe un code de autorización de Spotify. La API usa este código para solicitar automáticamente un access_token y un refresh_token. Estos tokens se guardan en la base de datos asociados al ID del usuario de Spotify.

IMPORTANTE: HTTPS Requerido Spotify requiere que el redirect_uri sea una conexión segura (HTTPS). Durante el desarrollo en localhost, esto puede ser un problema. Se recomienda usar una herramienta como ngrok para exponer tu servidor local a internet a través de un túnel HTTPS.

Ejemplo con ngrok: ngrok http 8080. Ngrok te dará una URL https://<random-string>.ngrok.io, la cual deberás registrar como tu redirect_uri en el dashboard de Spotify y en tu archivo .env.

Endpoints de la API

Agregar una Canción a una Playlist

• Endpoint: POST /api/v1/canciones/agregar
• Descripción: Añade una canción específica a una playlist específica en nombre de un usuario. El sistema usa el spotify-id para buscar el token guardado en la base de datos y lo refresca si es necesario antes de hacer la llamada a Spotify.
• Parámetros de Consulta (Query Params):
  • spotify-id (string, requerido): La ID del usuario de Spotify.
  • playlist_id (string, requerido): La ID de la playlist de destino.
  • song_id (string, requerido): La ID de la canción a añadir.
• Ejemplo de Petición (curl):

  curl -X POST "http://localhost:8080/api/v1/canciones/agregar?spotify-id=1122334455&playlist_id=37i9dQZF1DXcBWIGoYBM5M&song_id=4iV5W9uYEdYUVa79Axb7Rh"

Funcionalidades Futuras (Pendientes)

Este proyecto sienta las bases para una herramienta más completa. Las siguientes funcionalidades están planeadas para el futuro:

• Gestión de Playlists: Endpoints para crear nuevas playlists, renombrarlas o eliminarlas.
• Gestión de Canciones: Endpoints para eliminar canciones de una playlist o cambiar su orden.
• Obtener Canciones en Cola: Un endpoint para consultar las canciones actuales en la playlist, permitiendo al bot o a una interfaz mostrar la cola de reproducción.
• Seguridad Mejorada: Implementar validación del parámetro state en el flujo OAuth para prevenir ataques CSRF.