Concepts

Un client par API

Un client HTTP Guardian représente une API cible : baseUrl, authentification, parseur, cache, guards, notifier et plugins. Si l'application parle à deux backends, créer deux clients. Cela évite les options conditionnelles partout et rend les redirections, origines autorisées et en-têtes globaux plus faciles à auditer.

Résultat explicite

Les appels get, post, put, patch et delete retournent un ClientResult<T>. Le consommateur teste result.ok au lieu d'attraper des exceptions pour les erreurs API normales.

type ClientResult<T> =
  | { ok: true; status: number; headers: Headers; data: T; raw: unknown; url: string }
  | { ok: false; status: number; headers: Headers; errors: AppError[]; raw: unknown; url: string };

Une erreur réseau, une erreur HTTP et une erreur de parsing sont donc exposées avec le même modèle de lecture côté application.

Parseur avant UI

Le parseur transforme la réponse brute en contrat applicatif avant que l'UI ou les services métier ne la touchent. Une enveloppe REST, Laravel, Nest, GraphQL ou maison doit être normalisée une seule fois.

La règle est simple : si deux composants connaissent la structure brute du backend, le parseur est probablement au mauvais endroit.

Guards comme pipeline

Les guards se comportent comme des middlewares autour de fetch. Ils reçoivent un contexte, peuvent enrichir headers/méta, appeler next(ctx), puis inspecter la réponse.

Ordre recommandé :

1. Auth interne.
2. CSRF ou correlation.
3. Idempotence et retry.
4. Refresh auth.
5. Instrumentation et notifications.

L'ordre doit être documenté dans l'application consommatrice quand il a une conséquence produit.

Plugins pour les politiques transverses

Les plugins évitent de répéter logger, Sentry, OpenTelemetry, retry, timeout ou rate limit dans chaque service. Ils sont utiles quand le comportement appartient à l'API entière, pas à une seule requête.