🚀 API GERO — Stats : vue d’ensemble, auth, conventions

Pour qui ? Développeurs, intégrateurs, data/BI
Objet : Comprendre la surface /api/stats de GERO telle qu’exposée par le service NestJS (controller AppController) et démarrer rapidement.

---

🧭 Périmètre

• Type d’API : REST JSON (NestJS)
• Doc interactive : Swagger UI (bouton Authorize disponible)
• Encodage : UTF-8, réponses JSON
• Horodatage : ISO-8601 en UTC recommandé pour les paramètres start / end

ℹ️ Le service prépare des agrégations par événement (:eventId) et par fenêtre temporelle (start, end).
Les réponses suivent deux modèles simples :

• GroupCountStat[] → [{ name: string, value: number }]
• SeriesStat[] → [{ name: string, series: [{ name: string, value: number }] }]

---

🔐 Authentification

Le controller est annoté @ApiBasicAuth() et protégé par un @UseGuards(AuthGuard).
Côté client, utilisez HTTP Basic sur HTTPS :

Authorization: Basic <base64(username:password)>

• Identifiants fournis par GERO (compte technique / partner).
• Sur Swagger UI, cliquez Authorize, sélectionnez Basic et renseignez vos credentials.
• Si un autre schéma est activé dans ton instance (token, header custom), garde la même logique de header d’auth sur chaque requête.

---

📌 Conventions d’appel

• Path param : :eventId (identifiant d’événement)
• Query params :
• start, end (obligatoires sur la plupart des routes) — ISO-8601 recommandé
• Exemple : start=2024-10-15T00:00:00.000Z&end=2024-10-16T00:00:00.000Z
• Codes de retour :
• 200 OK : succès (peut renvoyer [] si aucun résultat)
• 401/403 : authentication/authorization manquante
• 4xx : paramètres invalides (format de date, eventId…)
• 5xx : erreur serveur / backend datastore

---

🧪 Exemples génériques

cURL (Basic Auth)

curl -u "<USERNAME>:<PASSWORD>" \
  -H "Accept: application/json" \
  "https://app.gero.fr/api/stats/<eventId>/incidents/total?start=2024-10-15T00:00:00.000Z&end=2024-10-16T00:00:00.000Z"

JavaScript (fetch)

const url = new URL(`https://app.gero.fr/api/stats/${eventId}/patients/sex`);
url.searchParams.set('start', '2024-10-15T00:00:00.000Z');
url.searchParams.set('end',   '2024-10-16T00:00:00.000Z');

const res = await fetch(url, {
  headers: {
    'Accept': 'application/json',
    'Authorization': 'Basic ' + btoa(username + ':' + password)
  }
});
const data = await res.json(); // -> GroupCountStat[]

---

🧱 Bonnes pratiques

• Dates ISO UTC systématiques (YYYY-MM-DDTHH:mm:ss.sssZ).
• Gérer le cas “aucune donnée” : beaucoup d’endpoints renvoient [] si vide.
• Idempotence : ce sont des GET de lecture d’agrégats, aucune mutation.
• Throttling côté client si vous enchaînez de grands intervalles (ex. par heure sur une semaine) : privilégiez des fenêtres raisonnables.

---

🩺 Healthcheck

• GET /healthz → Stats service online (non authentifié, @ApiExcludeEndpoint), utile pour supervision.