Utilisation de l'API — Headers & Rate Limits

Ce chapitre couvre les headers HTTP, les règles CORS et le throttling. Lisez Conventions REST d'abord.

---

Headers requis

Appels frontend (Bearer + enriched)

httpCopier
Authorization: Bearer <keycloak_access_token>
x-enriched-token: <wakastart_token>
Content-Type: application/json

Appels backend (API Key)

httpCopier
x-api-key: sk_live_...
Content-Type: application/json

---

Headers optionnels

Exemple avec trace ID :

typescriptCopier
const traceId = crypto.randomUUID();

const response = await fetch(apiUrl, {
  headers: {
    "Authorization":    `Bearer ${accessToken}`,
    "x-enriched-token": enrichedToken,
    "x-trace-id":       traceId,
    "Content-Type":     "application/json",
  },
});

// Le request-id est dans la réponse pour le support
const requestId = response.headers.get("x-request-id");

---

CORS

L'API WakaStart supporte CORS pour les origines enregistrées. Les règles :

• Origines autorisées : configurées dans ALLOWED_ORIGINS côté API.
• Credentials : Access-Control-Allow-Credentials: true — les cookies HttpOnly sont transmis.
• Méthodes : GET, POST, PUT, PATCH, DELETE, OPTIONS.
• Headers exposés : x-request-id, Retry-After.

Appels directs depuis le browser : si votre frontend appelle l'API sans proxy, le cookie wakastart_token est HttpOnly et inaccessible depuis JavaScript. Vous ne pouvez pas passer x-enriched-token côté browser sans proxy. Utilisez toujours un proxy serveur.

---

Idempotence

Les opérations GET, PUT et DELETE sont idempotentes. Pour POST :

• Création d'invitation : si une invitation PENDING existe déjà pour le même email + Customer, l'API répond 409 Conflict. C'est sûr de retenter après un échec réseau.
• Enrichissement : /api/auth/enrich est idempotent pour un même access_token dans sa période de validité.
• Token refresh : /api/auth/token/refresh génère un nouveau token à chaque appel. Ne pas appeler en parallèle.

---

Rate limiting

L'API applique trois niveaux de throttling :

Limites spécifiques par endpoint

Réponse 429 :

jsonCopier
{ "statusCode": 429, "message": "Too Many Requests" }

Le header Retry-After indique la durée d'attente en secondes.

---

Backoff exponentiel

typescriptCopier
async function fetchWithRetry(
  url: string,
  options: RequestInit,
  maxRetries = 3
): Promise<Response> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const res = await fetch(url, options);
    if (res.status !== 429) return res;

    const retryAfter = parseInt(res.headers.get("Retry-After") ?? "1", 10);
    const delay = retryAfter * 1000 * Math.pow(2, attempt);
    await new Promise(r => setTimeout(r, delay));
  }
  throw new Error("Rate limit exceeded after retries");
}

---

Vérification de droits depuis votre backend

httpCopier
POST /api/token/authorize
x-api-key: sk_live_...
Content-Type: application/json

{
  "token": "eyJ...",
  "checks": {
    "adminLevel": { "requiredLevel": "CustomerAdmin" },
    "roles": { "roles": ["CONFIG"], "mode": "any" },
    "appRights": { "rights": ["users.create"], "mode": "all" }
  }
}

jsonCopier
{
  "authorized": true,
  "details": {
    "adminLevel": { "hasLevel": true,  "actualLevel": "NetworkAdmin" },
    "roles":      { "hasRoles": true,  "matchedRoles": ["CONFIG"] },
    "appRights":  { "hasRights": true, "missingRights": [] }
  }
}

---

Bonnes pratiques

• Headers ne se cumulent pas : un appel avec x-api-key ET Authorization: Bearer verra la clé API prévaloir.
• Toujours propager x-trace-id : indispensable pour le support en cas d'erreur 5xx.
• Logger le x-request-id de la réponse sur les erreurs 5xx.
• Respecter Retry-After : ne pas ignorer ce header, il protège la stabilité de l'API.

Pièges classiques

• Appels parallèles au refresh : si plusieurs requêtes expirent en même temps et tentent toutes un refresh simultané, une seule réussit. Implémenter un mutex côté client.
• Rate limit sur les tests : en CI, une batterie de tests peut déclencher le rate limit de courte durée. Ajouter des délais entre les tests d'intégration.

Aller plus loin

• Erreurs HTTP : codes 429 et 401 détaillés
• Bonnes pratiques sécurité : tokens, secrets, HTTPS