b3ni/quasar

Fork 0

Files

Benito Rodríguez 2667e11284

CI / lint (push) Failing after 10s

Details

CI / test-backend (push) Has been skipped

Details

CI / test-frontend (push) Has been skipped

Details

CI / test-e2e (push) Has been skipped

Details

Refactor code structure for improved readability and maintainability

2026-03-22 11:34:38 +01:00

25 KiB

Raw Blame History

APIs del Sistema — Guía completa

Este documento integra toda la información sobre APIs del sistema: obtención de claves, prioridades, estrategias, comparación y configuración.

APIs priorizadas (MVP)

Prioridad Alta

IGDB (Internet Game Database) - Calidad superior, amplia cobertura
RAWG (Rawg.io) - Buena cobertura, datos de tiendas

Prioridad Media

TheGamesDB - Artwork comunitario
ScreenScraper - Media específica para ROMs

Prioridad Baja (para futuras versiones)

PriceCharting - Precios físicos
IsThereAnyDeal - Ofertas digitales
MobyGames - Datos históricos detallados
eBay - Datos de mercado

Obtención de claves

IGDB (Internet Game Database)

IGDB usa OAuth 2.0 via Twitch. Steps:

Go to Twitch Developer Console
Sign in with your Twitch account (create one if needed)
Click "Create Application"
- Name: "Quasar" (or your app name)
- Category: Select relevant category
- Accept terms, click Create
You'll see:
- Client ID — Copy this
- Click "New Secret" to generate Client Secret — Copy this
Go to Settings → OAuth Redirect URLs
- Add: http://localhost:3000/oauth/callback (development)
- For production: https://yourdomain.com/oauth/callback

In your .env file:

IGDB_CLIENT_ID=your_client_id
IGDB_CLIENT_SECRET=your_client_secret

Start Quasar, it will use IGDB automatically

Rate Limit: 4 requests/second

RAWG (Rawg.io)

RAWG has a simpler API Key approach:

Go to RAWG Settings
Sign up if needed, then login
Find "API Key" section
Click "Create new key" (if needed) or copy existing key
In your .env file:
```
RAWG_API_KEY=your_api_key_here
```
Start Quasar

Rate Limit: 20 requests/second (free tier)

Note: RAWG requires attribution in UI (include "Powered by RAWG" somewhere visible)

TheGamesDB (thegamesdb.net)

TheGamesDB uses a simple API Key:

Go to TheGamesDB API
Find "API Key" section (free registration required)
Register or login
Copy your API key
In your .env file:
```
THEGAMESDB_API_KEY=your_api_key_here
```
Start Quasar

Rate Limit: 1 request/second (free tier)

ScreenScraper

ScreenScraper requiere cuenta y modelo de donación:

Go to ScreenScraper
Create account
Niveles de donación ofrecen límites distintos (ej.: 50.000 scrapes/día en nivel Bronze)

En tu .env file:

SCREENSCRAPER_USERNAME=your_username
SCREENSCRAPER_PASSWORD=your_password

Guía de integración

IGDB

Obtener credenciales: registrar una app en Twitch Developer Console para obtener CLIENT_ID y CLIENT_SECRET. Obtener token con grant type client_credentials (POST a https://id.twitch.tv/oauth2/token).
Endpoints principales: POST https://api.igdb.com/v4/games (consulta flexible via body con sintaxis IGDB), POST https://api.igdb.com/v4/covers, POST https://api.igdb.com/v4/platforms.
Ejemplo (buscar):

# Obtener token
curl -X POST 'https://id.twitch.tv/oauth2/token?client_id=$IGDB_CLIENT_ID&client_secret=$IGDB_CLIENT_SECRET&grant_type=client_credentials'

# Buscar juegos
curl -X POST 'https://api.igdb.com/v4/games' \
  -H "Client-ID: $IGDB_CLIENT_ID" \
  -H "Authorization: Bearer $IGDB_TOKEN" \
  -H 'Accept: application/json' \
  --data 'fields id,name,first_release_date,platforms.name,genres.name,cover.url; search "zelda"; limit 5;'

Respuesta (esquemática):

[
  {
    "id": 12345,
    "name": "Ejemplo",
    "first_release_date": 1459468800,
    "platforms": [{ "name": "Nintendo Switch" }],
    "cover": { "url": "//images.igdb.com/...jpg" }
  }
]

Límites y manejo: la API puede devolver 429 o cabeceras de límite; implementar retries exponenciales (ej. 3 intentos) y respetar Retry-After. Implementar circuit breaker si la API falla repetidamente.
Atribución: mostrar origen de datos (ej. "Datos: IGDB") según términos del servicio.

RAWG

Obtener credenciales: registrarse en RAWG para obtener RAWG_API_KEY (https://rawg.io/apidocs).
Endpoints principales: GET https://api.rawg.io/api/games?key=API_KEY&search=..., GET https://api.rawg.io/api/games/{id}.
Ejemplo:

curl 'https://api.rawg.io/api/games?key=$RAWG_API_KEY&search=zelda&page_size=5'

Respuesta (esquemática):

{
  "count": 100,
  "results": [
    { "id": 3498, "name": "GTA V", "released": "2013-09-17", "background_image": "https://..." }
  ]
}

Límites y manejo: RAWG suele tener límites por clave/plan; cachear y fallback a otros proveedores si falla.
Atribución: revisar condiciones y mostrar HTTP o texto de fuente si es requerido por el proveedor.

TheGamesDB

Obtener credenciales: crear cuenta y generar API Key en https://thegamesdb.net.
Endpoints: búsqueda por nombre y detalles (/v1/Games/ByGameName?name=..., /v1/Games/ByGameID?id=...).
Ejemplo:

curl -H 'Authorization: Bearer $THEGAMESDB_KEY' 'https://api.thegamesdb.net/v1/Games/ByGameName?name=zelda'

Estrategia de fallback y normalización

Orden de prioridad: IGDB → RAWG → TheGamesDB (configurable).
Normalización (mapping):
- title ← name
- platform ← platforms[].name
- release_date ← first_release_date / released → convertir a ISO 8601
- genres ← genres[].name
- cover_url ← cover.url / background_image
- external_ids ← { igdb: id, rawg: id, thegamesdb: id }
Fallback: si IGDB no tiene portada, intentar RAWG; si falla, usar TheGamesDB. Registrar la fuente usada.

Caché y almacenamiento de artwork

Caché metadata: LRU en memoria o Redis con TTL (por ejemplo 24h) para evitar sobrecargar APIs.
Almacenamiento de imágenes: descargar y optimizar con sharp (crear versiones: thumb, medium), almacenar en storage/artwork/{gameId}/cover.jpg o S3.
Servicio proxy: servir imágenes desde backend para no exponer keys ni URLs externas.

Manejo de errores y resiliencia

Implementar retries exponenciales con jitter (3 intentos).
Implementar circuit breaker para desconectar llamadas a un proveedor fuera de servicio por N minutos.
Limitar concurrencia por proveedor (p. ej. 5 llamadas simultáneas) y usar colas para trabajos masivos (enriquecimiento masivo).

Comparación detallada

Resumen por API

IGDB (Internet Games Database)

Resumen: Base de datos muy completa (propiedad de Twitch/Amazon) con endpoints para juegos, covers, screenshots, plataformas, ratings, compañías y más.
Autenticación / Requisitos: OAuth vía Twitch (Client ID + Client Secret → token) — requiere cuenta Twitch y 2FA para registrar apps.
Datos principales: covers, screenshots, genres, developers, ESRB/PEGI, platforms, videos, websites, age ratings, tags.
Rate limits / cuotas: 4 peticiones/segundo; hasta 8 peticiones abiertas (si se excede → 429 Too Many Requests).
Fecha verificación: 2026-02-07
TOS / Developer Agreement: Twitch Developer Service Agreement — https://www.twitch.tv/p/legal/developer-agreement/
Cláusula clave: "There is a rate limit of 4 requests per second. If you go over this limit you will receive a response with status code 429 Too Many Requests." — https://api-docs.igdb.com/
Costes / modelo: Gratuito para uso no comercial; acuerdos comerciales para partners (atribución en caso de partnership).
Enlace: https://api-docs.igdb.com/

RAWG

Resumen: Gran base de datos (medio millón de juegos), buena para metadata general y enlaces a tiendas.
Autenticación / Requisitos: API key en query string (key=YOUR_API_KEY).
Datos principales: descripciones, screenshots, plataformas, géneros, ratings, enlaces a tiendas, playtime estimado.
Rate limits / cuotas: Planes gratuitos con límites (ej. free tier limitada) y planes comerciales con mayor cuota (p.ej. hasta 50k requests/mes en planes de negocio).
Fecha verificación: 2026-02-07
TOS / Developer Agreement: https://rawg.io/tos_api
Cláusula clave: "Free for personal use as long as you attribute RAWG as the source of the data and/or images and add an active hyperlink from every page where the data of RAWG is used. No data redistribution." — https://rawg.io/tos_api
Costes / modelo: Free tier para proyectos personales; planes comerciales (pago mensual) para uso en productos con gran tráfico.
Enlace: https://rawg.io/apidocs

TheGamesDB

Resumen: Base de datos comunitaria para juegos y artwork, con API pública v2.
Autenticación / Requisitos: Registro y uso de API key (ver docs); repositorio público del proyecto (GPLv3 para el código del servidor).
Datos principales: imágenes, covers, plataformas, metadatos básicos.
Rate limits / cuotas: No siempre documentados públicamente (consultar docs/registro).
Fecha verificación: 2026-02-07
TOS / Developer Agreement: No documentado públicamente — consultado https://api.thegamesdb.net/ y https://github.com/TheGamesDB/TheGamesDBv2 (código bajo GPL‑3.0)
Cláusula clave: No documentado públicamente — verificar con el equipo de TheGamesDB antes de uso comercial/redistribución.
Enlace: https://api.thegamesdb.net/

ScreenScraper

Resumen: Servicio francés orientado a frontends, con enorme cantidad de media y opciones de scraping.
Autenticación / Requisitos: Cuenta en ScreenScraper; modelo de soporte/donación que habilita límites mayores.
Datos principales: screenshots, boxart, videos, manuals, metadata comunitaria.
Rate limits / cuotas: Planes por donación (ej.: 50.000 scrapes/día en niveles básicos; aumentos en niveles superiores).
Fecha verificación: 2026-02-07
TOS / Developer Agreement: https://www.screenscraper.fr/
Cláusula clave: "Niveles de donación ofrecen límites distintos (p.ej. 50.000 scrapes/día en nivel Bronze); consultar la cuenta para límites exactos." — https://www.screenscraper.fr/
Costes / modelo: Donación / suscripción para aumentar cuotas y velocidad.
Enlace: https://www.screenscraper.fr/

MobyGames

Resumen: Base histórica con screenshots, covers, reviews y credits; muy usada por investigación y metadata profunda.
Autenticación / Requisitos: API y/o MobyPlus; la API requiere registro y suscripción.
Datos principales: screenshots, covers, credits, precios históricos limitados.
Rate limits / cuotas: Non-commercial API requests are limited to 720 per hour (one every five seconds) with a max request rate of 1 per/second.
Fecha verificación: 2026-02-07
TOS / Developer Agreement: https://www.mobygames.com/api/subscribe/
Cláusula clave: "Non-commercial API requests are limited to 720 per hour (one every five seconds) with a max request rate of 1 per/second." — https://www.mobygames.com/api/subscribe/
Costes / modelo: Acceso vía suscripción / MobyPro; contactar para condiciones comerciales.
Enlace: https://www.mobygames.com/api/subscribe/

PriceCharting

Resumen: Fuente especializada en historial de precios para juegos físicos y coleccionables.
Autenticación / Requisitos: API documentada en el sitio; el acceso completo requiere suscripción / token pagado.
Datos principales: precios históricos, condiciones (complete, loose), plataforma y comparables de mercado.
Rate limits / cuotas: No siempre publicadas públicamente; contactar a PriceCharting para detalles.
Fecha verificación: 2026-02-07
TOS / Developer Agreement: https://www.pricecharting.com/api-documentation (ver también https://www.pricecharting.com/page/terms-of-service)
Cláusula clave: "API's are a premium tool. You must have a paid subscription to access the API." — https://www.pricecharting.com/api-documentation
Costes / modelo: Servicio comercial (licencias / API keys pagadas).
Enlace: https://www.pricecharting.com/api-documentation

IsThereAnyDeal (Itad)

Resumen: Agregador de ofertas con histórico y mapeo de keys/tiendas; útil para tracking de ofertas digitales.
Autenticación / Requisitos: API Key (docs en https://docs.isthereanydeal.com/).
Datos principales: price history, deals, store IDs, game mappings.
Rate limits / cuotas: Access to API is rate limited and subject to change (limits provided in headers); contactar si necesita mayor cuota.
Fecha verificación: 2026-02-07
TOS / Developer Agreement: https://docs.isthereanydeal.com/
Cláusula clave: "You MUST NOT change provided data in any way. You SHOULD provide a link to IsThereAnyDeal.com or mention IsThereAnyDeal API." — https://docs.isthereanydeal.com/
Costes / modelo: Free tier; acuerdos comerciales para uso intensivo.
Enlace: https://docs.isthereanydeal.com/

eBay

Resumen: Fuente de datos de mercado (listings, precios vendidos) para estimar valor real de mercado.
Autenticación / Requisitos: Registro en eBay Developers Program; claves y OAuth para endpoints de venta/completed items.
Datos principales: listados, historiales vendidos (completed), especificaciones de artículos.
Rate limits / cuotas: Límite de llamadas por aplicación; eBay puede limitar y suspender acceso si se exceden los límites.
Fecha verificación: 2026-02-07
TOS / Developer Agreement: https://developer.ebay.com/join/api-license-agreement
Cláusula clave: "You may not sell, rent, trade, distribute, lease (or otherwise commercialize), copy, store or modify eBay Content, other than for the purposes allowed by this API License Agreement." y "eBay reserves the right to limit the number of periodic API calls you are allowed to make." — https://developer.ebay.com/join/api-license-agreement
Costes / modelo: Free para desarrolladores con límites; uso intensivo o comerciales pueden requerir acuerdos o certificaciones.
Enlace: https://developer.ebay.com/

Tabla resumida

API	Data types	Auth	Free / Paid	Fecha verificación	Licencia / Nota legal	Notes
IGDB	covers, screenshots, genres, ESRB, companies, platforms	OAuth via Twitch	Free (non-commercial); commercial partners	2026-02-07	TOS: https://www.twitch.tv/p/legal/developer-agreement/	4 rps rate limit; muy completa
RAWG	games, screenshots, stores, ratings, playtime	API key (query param)	Free tier; paid commercial plans	2026-02-07	TOS: https://rawg.io/tos_api (atribución requerida)	Free for personal use; atribución requerida; no redistribución
TheGamesDB	images, basic metadata	API key (registro)	Free / community	2026-02-07	Repo/TOS: https://github.com/TheGamesDB/TheGamesDBv2 (codigo GPL-3.0) / TOS no documentada públicamente	No TOS público claro; código backend GPL‑3.0
ScreenScraper	images, videos, manuals	Account + token (donation tiers)	Donation / paid tiers	2026-02-07	TOS: https://www.screenscraper.fr/ (donation/tiers)	Donación/premium para mayores cuotas (p.ej. 50k/día)
PriceCharting	price history	API key / commercial	Paid	2026-02-07	Paid: https://www.pricecharting.com/api-documentation	API premium; requiere suscripción
IsThereAnyDeal	deals, price history	API key	Free tier / paid	2026-02-07	TOS: https://docs.isthereanydeal.com/	Requiere atribución; prohíbe modificar datos
MobyGames	screenshots, credits, covers	Subscribe / API key	Paid / subscription	2026-02-07	Paid/Subscribe: https://www.mobygames.com/api/subscribe/	Access via subscription; non-commercial rate limits documented
eBay	listings, sold data	eBay Dev keys / OAuth	Free (with limits)	2026-02-07	TOS: https://developer.ebay.com/	Terms restrict distribution; API License Agreement

Conclusión y recomendación para MVP

Recomiendo un set inicial de APIs (priorizado): IGDB, RAWG, TheGamesDB, ScreenScraper, PriceCharting, IsThereAnyDeal.

Por qué: IGDB + RAWG cubren amplia metadata y campos útiles (genres, plataformas, covers); TheGamesDB aporta artwork comunitario; ScreenScraper cubre assets específicos para ROM/frontends (videos/logos); PriceCharting e IsThereAnyDeal cubren precios físicos y ofertas digitales respectivamente.
Prioridad: 1) IGDB (calidad + licencia accesible) 2) RAWG (cobertura y datos de tiendas) 3) TheGamesDB (artwork) 4) ScreenScraper (media específica) 5) PriceCharting (precios físicos) 6) IsThereAnyDeal (ofertas digitales).

Estrategias técnicas

Variables de entorno (ejemplos)

IGDB_CLIENT_ID=...
IGDB_CLIENT_SECRET=...
RAWG_API_KEY=...
THEGAMESDB_API_KEY=...
SCREENSCRAPER_USERNAME=...
SCREENSCRAPER_PASSWORD=...
EXTERNAL_API_CONCURRENCY=5

Nota: Nunca exponer estas claves en el cliente; siempre pasar por el backend.

Normalización de datos

interface NormalizedGame {
  title: string;
  platform: string;
  release_date: string; // ISO 8601
  genres: string[];
  cover_url: string;
  external_ids: {
    igdb?: string;
    rawg?: string;
    thegamesdb?: string;
  };
  source: 'igdb' | 'rawg' | 'thegamesdb' | 'screenscraper';
}

Ejemplo de implementación

class MetadataService {
  private apis = [
    new IGDBService(),
    new RAWGService(),
    new TheGamesDBService(),
    new ScreenScraperService(),
  ];

  async searchGame(title: string): Promise<NormalizedGame> {
    for (const api of this.apis) {
      try {
        const result = await api.search(title);
        if (result) {
          return this.normalize(result, api.getSource());
        }
      } catch (error) {
        console.warn(`${api.getSource()} failed:`, error);
        continue;
      }
    }
    throw new Error('All APIs failed');
  }

  private normalize(data: any, source: string): NormalizedGame {
    return {
      title: data.name || data.title,
      platform: data.platforms?.[0]?.name || '',
      release_date: this.normalizeDate(data.first_release_date || data.released),
      genres: data.genres?.map((g: any) => g.name) || [],
      cover_url: data.cover?.url || data.background_image || '',
      external_ids: {
        igdb: data.id,
        rawg: data.id,
        thegamesdb: data.id,
      },
      source: source as any,
    };
  }
}

Configuración y despliegue

Configuración de variables de entorno

Para configurar las credenciales de las APIs externas en Quasar, sigue estos pasos:

1. Archivo `.env`

El archivo backend/.env contiene las variables de entorno necesarias. Este archivo NO debe ser commiteado al repositorio (ya está incluido en .gitignore).

2. Variables requeridas

Añade las siguientes variables a tu archivo backend/.env:

# IGDB (Internet Game Database)
IGDB_CLIENT_ID=your_igdb_client_id_here
IGDB_CLIENT_SECRET=your_igdb_client_secret_here

# RAWG Video Games Database
RAWG_API_KEY=your_rawg_api_key_here

# TheGamesDB
THEGAMESDB_API_KEY=your_thegamesdb_api_key_here

3. Archivo de ejemplo

El archivo backend/.env.example contiene todas las variables de entorno disponibles con sus descripciones. Úsalo como referencia cuando configures tu entorno.

4. Instrucciones detalladas por API

Consulte la sección Obtención de claves para instrucciones detalladas sobre cómo obtener cada credencial:

IGDB: https://dev.twitch.tv/console
RAWG: https://rawg.io/apicreate
TheGamesDB: https://thegamesdb.net/api.php

Testing Without Real Keys

Para desarrollo/testing:

Dejar API keys como your_*_here en .env.local
Quasar will gracefully degrade and show limited metadata
Frontend will still work with manual game entry

Production Deployment

Para producción:

Generar nuevas claves en cada servicio (no reutilizar claves de desarrollo)
Almacenar claves en Gitea Secrets (para pipelines CI/CD automatizados)
O usar variables de entorno en tu proveedor de hosting
Rotar claves cada 3 meses
Monitorear límites de rate en los dashboards de los servicios

Gitea Actions CI/CD Setup

Para habilitar pruebas automatizadas con API keys en Gitea Actions:

1. Store Secrets in Gitea

Navigate to your repository settings:

https://your-gitea-instance/your-org/quasar/settings/secrets/actions

Add these secrets:

IGDB_CLIENT_ID (from Twitch Developer Console)
IGDB_CLIENT_SECRET (from Twitch Developer Console)
RAWG_API_KEY (from RAWG settings)
THEGAMESDB_API_KEY (from TheGamesDB API)
SCREENSCRAPER_USERNAME (from ScreenScraper)
SCREENSCRAPER_PASSWORD (from ScreenScraper)

2. Workflow Configuration

The .gitea/workflows/ci.yml workflow automatically:

✅ Installs dependencies
✅ Runs linting checks
✅ Executes backend tests (Vitest)
✅ Executes frontend tests (Vitest)
✅ Starts backend + frontend servers
✅ Runs E2E tests (Playwright) with real metadata APIs
✅ Uploads test reports on failure

3. Testing Flow

Push code to main or develop
Gitea Actions picks up the .gitea/workflows/ci.yml
Secrets are injected as environment variables
E2E tests fetch real metadata from APIs (using injected secrets)
Build fails if any test fails (prevents broken code)

4. Local Development

For local testing, use .env.local:

IGDB_CLIENT_ID=your_local_id
IGDB_CLIENT_SECRET=your_local_secret
RAWG_API_KEY=your_local_key
THEGAMESDB_API_KEY=your_local_key
SCREENSCRAPER_USERNAME=your_username
SCREENSCRAPER_PASSWORD=your_password

Note: CI/CD uses Gitea Secrets (not .env files), so never commit real credentials.

Troubleshooting

"IGDB_CLIENT_ID not found" → Check .env file exists and has correct format

"429 Too Many Requests" → Rate limit exceeded, wait and retry

"Invalid API Key" → Copy key exactly (no spaces), verify it's active on service website

"ScreenScraper authentication failed" → Check donation level and account status

Fuentes

IGDB API docs: https://api-docs.igdb.com/ — TOS: https://www.twitch.tv/p/legal/developer-agreement/
RAWG API & TOS: https://rawg.io/apidocs / https://rawg.io/tos_api
TheGamesDB API / repo: https://api.thegamesdb.net/ / https://github.com/TheGamesDB/TheGamesDBv2/blob/master/LICENSE
ScreenScraper: https://www.screenscraper.fr/
MobyGames API: https://www.mobygames.com/api/subscribe/
PriceCharting API & Terms: https://www.pricecharting.com/api-documentation / https://www.pricecharting.com/page/terms-of-service
IsThereAnyDeal docs/TOS: https://docs.isthereanydeal.com/
eBay API License Agreement: https://developer.ebay.com/join/api-license-agreement

Metadatos

Autor: Quasar (investigación automatizada)
Fecha verificación: 2026-02-07
Última actualización: 2026-02-07

Nota: Si quieres, puedo preparar una matriz técnica (endpoints concretos, ejemplos de requests y una PoC de integración para 2 APIs prioritarias).

25 KiB Raw Blame History Unescape Escape

APIs del Sistema — Guía completa

Tabla de Contenidos

APIs priorizadas (MVP)

Prioridad Alta

Prioridad Media

Prioridad Baja (para futuras versiones)

Obtención de claves

IGDB (Internet Game Database)

RAWG (Rawg.io)

TheGamesDB (thegamesdb.net)

ScreenScraper

Guía de integración

IGDB

RAWG

TheGamesDB

Estrategia de fallback y normalización

Caché y almacenamiento de artwork

Manejo de errores y resiliencia

Comparación detallada

Resumen por API

IGDB (Internet Games Database)

RAWG

TheGamesDB

ScreenScraper

MobyGames

PriceCharting

IsThereAnyDeal (Itad)

eBay

Tabla resumida

Conclusión y recomendación para MVP

Estrategias técnicas

Variables de entorno (ejemplos)

Normalización de datos

Ejemplo de implementación

Configuración y despliegue

Configuración de variables de entorno

1. Archivo .env

2. Variables requeridas

3. Archivo de ejemplo

4. Instrucciones detalladas por API

Testing Without Real Keys

Production Deployment

Gitea Actions CI/CD Setup

1. Store Secrets in Gitea

2. Workflow Configuration

3. Testing Flow

4. Local Development

Troubleshooting

Fuentes

Metadatos

25 KiB

Raw Blame History

1. Archivo `.env`