Documentation API

Référence des endpoints exposés par l’application. Les chemins sont relatifs à l’origine du site (ex. /api/recommend-skills). Spécification machine-readable : GET /api/docs, GET /api/openapi.

Ouvrir Swagger UI →

• GET/api/session

  Établit la session : le backend appelle l’API d’auth avec AUTH_API_SECRET, pose un cookie (d4_session_id), retourne sessionId. Aucune clé côté client.

  Réponses

  • 200Succès{ sessionId: string }
  • 401Non authentifié (connectez-vous ou vérifiez AUTH_API_SECRET){ error: string }
• POST/api/session/signout

  Supprime le cookie de session.

  Réponses

  • 200Succès{ ok: true }
• GET/api/builds

  Liste des builds de la session (cookie).

  Réponses

  • 200Succès{ builds: Build[] }
  • 500Erreur serveur{ error: string }
• POST/api/builds

  Crée un build (propriétaire = session du cookie).

  Corps de la requête

  Content-Type: application/json · Requis : name, d4Class, season, hardcore, level

  BuildInput (name, d4Class, season, hardcore, level, tags, notes, source, steps, stepsSuggestions, …)

  Réponses

  • 200Build crééBuild
  • 401Session manquante{ error: string }
  • 500Erreur serveur{ error: string }
• GET/api/builds/[id]

  Détail d’un build par ID.

  Réponses

  • 200SuccèsBuild
  • 403Accès refusé{ error: string }
  • 404Build introuvable{ error: string }
  • 500Erreur serveur{ error: string }
• PATCH/api/builds/[id]

  Met à jour un build (session = propriétaire).

  Corps de la requête

  Content-Type: application/json

  Partial<BuildInput>

  Réponses

  • 200Build mis à jourBuild
  • 401Session manquante{ error: string }
  • 403Accès refusé{ error: string }
  • 404Build introuvable{ error: string }
  • 500Erreur serveur{ error: string }
• DELETE/api/builds/[id]

  Supprime un build (session = propriétaire).

  Réponses

  • 200Succès{ ok: true }
  • 401Session manquante{ error: string }
  • 403Accès refusé{ error: string }
  • 404Build introuvable{ error: string }
  • 500Erreur serveur{ error: string }
• GET/api/docs

  Retourne la spécification des API au format JSON (envelope normalisé) pour intégration avec des outils.

  Réponses

  • 200Spécification JSON (donnees = spec OpenAPI)OpenAPI 3.0 paths + info
• GET/api/openapi

  Spécification OpenAPI 3.0 brute (pour Swagger UI, Postman, codegen). Même contenu que donnees de GET /api/docs.

  Réponses

  • 200Spec OpenAPI 3.0 (JSON brut)OpenAPI 3.0
• POST/api/recommend-skills

  Retourne des recommandations de répartition de points de compétences pour un build D4, selon le niveau et l’arbre actuel. Appelle l’API ai-smart-router (URL en config frontend, secret backend uniquement).

  Corps de la requête

  Content-Type: application/json · Requis : level, d4Class

  {
    level: number;      // niveau du personnage (1-100)
    d4Class: string;   // "barbarian" | "sorcerer" | "rogue" | "druid" | "necromancer" | "paladin"
    skillTree: string; // contenu texte de l'arbre (sections | compétences | points | upgrade)
  }

  Réponses

  • 200Succès{ recommendations: Array<{ skill: string; addPoints: number; reason?: string }> }
  • 400Paramètres manquants ou invalides{ error: string }
  • 429Quota dépassé{ error: string }
  • 503AI_API_SECRET manquant (backend){ error: string }
  • 500Erreur serveur{ error: string }

  Exemple

  Requête

  {
    "level": 50,
    "d4Class": "sorcerer",
    "skillTree": "Core | Chain Lightning | 5 | ..."
  }

  Réponse

  {
    "recommendations": [
      { "skill": "Invigorating Conduit", "addPoints": 3, "reason": "Synergie mana" },
      { "skill": "Precision Magic", "addPoints": 2, "reason": "Crit chance" }
    ]
  }