Integración de APIs externas — Prioridad y guía práctica

Objetivo

Definir APIs prioritarias para el MVP, cómo obtener credenciales, ejemplos de uso y estrategias de robustez (rate limit, retries, fallback y normalización de datos).

APIs priorizadas (MVP)

IGDB (prioridad alta)
RAWG (prioridad alta)
TheGamesDB (prioridad media)

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).

Variables de entorno (ejemplos)

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

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

Fuentes

IGDB API docs, RAWG API docs, TheGamesDB API docs.
Patrones: retries, circuit breakers (ej. libraries: p-retry, cockatiel).

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

4.6 KiB Raw Blame History