ADR-0007 : gRPC entre services, REST en façade

Statut	Accepté
Date	2025-11
Décideurs	Équipe de développement Edukit
Périmètre	Edukit-OrgService, Edukit-VM, Edukit-Front

Contexte

Edukit a deux types de communications synchrones aux exigences opposées :

• En façade (interface web Angular vers les services, et tout client tiers éventuel) : besoin de compatibilité navigateur, de documentation lisible, de génération de client typé, et d’un format de débogage simple.
• Entre services (OrgService ↔ VmService, par exemple résolution des membres d’un groupe lors du calcul du résumé d’un environnement) : besoin de performance, de contrats fortement typés, et de faible surcoût, sans contrainte de compatibilité navigateur.

Imposer un seul protocole pour les deux usages obligerait à un compromis : REST partout laisse le surcoût JSON sur le chemin chaud inter-services ; gRPC partout impose une passerelle pour le navigateur et dégrade la lisibilité des API publiques.

Décision

Utiliser deux protocoles selon l’usage :

• REST (Minimal API) plus Swagger / OpenAPI en façade. Les deux services exposent une API REST documentée (Swagger UI avec déclaration de sécurité JWT porteur). L’interface web et tout client tiers peuvent générer un client typé depuis la spécification OpenAPI. Les opérations longues répondent en 202 Accepted et le suivi passe par SignalR.
• gRPC (HTTP/2 plus protobuf binaire) entre services. Les appels OrgService ↔ VmService passent par gRPC : talons fortement typés générés depuis les fichiers .proto, pas de surcoût de sérialisation JSON, canaux HTTP/2 mis en commun (Grpc.Net.ClientFactory).

Cette séparation est cohérente avec le découpage en services de l’ADR-0003 : façade publique en REST, communication interne en gRPC.

Conséquences

Bénéfices

• Performance sur le chemin interne : gRPC évite le surcoût JSON et réutilise les connexions HTTP/2, ce qui compte sur les appels fréquents entre services.
• Contrats internes fortement typés : les fichiers .proto font office de contrat partagé ; une rupture de contrat se voit à la compilation.
• Façade lisible et standard : OpenAPI permet la génération de client, la documentation interactive et le débogage simple côté navigateur.
• Compatibilité navigateur préservée : aucune passerelle gRPC-Web à opérer.

Coûts et limites

• Deux pratiques à maîtriser (REST et gRPC) plutôt qu’une seule. Le coût est limité car les deux sont natifs dans .NET 9.
• Contrats .proto à versionner et synchroniser entre services. Discipline à tenir lors des évolutions de contrat.
• gRPC est moins lisible au débogage que REST (binaire) : compensé par le fait qu’il est réservé au trafic interne, instrumenté par OpenTelemetry.

Alternatives écartées

• gRPC pour tout, y compris la façade : imposerait une passerelle gRPC-Web et dégraderait la lisibilité et la génération de client côté navigateur. Écarté.
• REST pour tout, y compris l’inter-services : laisserait le surcoût JSON sur le chemin chaud interne et perdrait le typage fort des contrats. Écarté pour la performance et la robustesse des contrats internes.
• GraphQL en façade : pertinent pour des besoins d’agrégation côté client riches, mais non justifié ici (les écrans consomment des ressources bien cadrées, et un endpoint de synthèse dédié couvre déjà l’agrégation des compteurs côté serveur).

Références

• Dossier B2, EADL-B2-C4 : « Contrats d’API et intégration avec l’interface web » et EADL-B2-C5 : « Choix technologiques argumentés ».
• Program.cs (Swagger plus JWT porteur), Grpc.Net.ClientFactory (canaux partagés).
• Voir aussi ADR-0003.