Diagramme d'architecture de passerelle API : routage, authentification, limites de débit et BFF

La passerelle API est la boîte que tous les diagrammes d'architecture contiennent et que peu expliquent. Elle se trouve en bordure et accumule des responsabilités avec le temps : routage, authentification, limites de débit, réécriture des requêtes, et parfois des règles métier qu'elle n'aurait jamais dû recevoir. Quand le diagramme montre seulement une flèche qui traverse une icône de passerelle, personne ne sait laquelle de ces tâches elle assure, et les questions surgissent pendant un incident plutôt qu'en revue.

Cet article construit un diagramme d'architecture de passerelle API pour une configuration courante : une application web, des applications mobiles et des partenaires derrière une seule passerelle, avec un backend par frontend. Il explique ce que la passerelle doit faire et ne pas faire, comment fonctionnent la vérification des jetons et les limites de débit, et ce qu'il faut étiqueter pour que le diagramme réponde à de vraies questions.

Ce qui a sa place dans la passerelle

Un répartiteur de charge distribue les requêtes entre les instances ; il ne sait pas qui est l'appelant. Un service mesh gère le trafic entre les services à l'intérieur du système. La passerelle gère le trafic qui arrive de l'extérieur et comprend les clients : leurs jetons, leurs routes et leurs quotas. Beaucoup de systèmes utilisent les trois.

La vérification des jetons en bordure

Dans l'exemple, les clients se connectent auprès du fournisseur d'identité et envoient un JSON Web Token (RFC 7519) avec chaque requête. La passerelle vérifie la signature avec les clés publiques du fournisseur, qu'elle récupère sous forme de document JWKS et met en cache, puis contrôle les claims : l'émetteur (iss), l'audience (aud) et l'expiration (exp).

Les bonnes pratiques actuelles pour les JWT de la RFC 8725 méritent d'être suivies ici. Une bibliothèque doit vous laisser spécifier les algorithmes autorisés et ne doit en utiliser aucun autre : configurez donc la liste au lieu de faire confiance à l'en-tête du jeton. Quand un même émetteur crée des jetons pour plusieurs applications, le jeton doit porter une audience, et chaque application doit vérifier que cette audience est bien la sienne.

Un jeton valide dit qui est l'appelant. Il ne dit pas ce qu'il a le droit de faire. La passerelle peut rejeter un scope manquant, mais c'est toujours le service qui décide si cet utilisateur peut modifier cette commande.

Les limites de débit

Comptez par client, pas par adresse IP. Derrière un NAT, de nombreux utilisateurs peuvent partager une adresse, et un seul robot d'extraction peut en utiliser beaucoup. Associez la limite à la clé d'API, au client OAuth ou à l'utilisateur.

Partagez les compteurs. Avec plusieurs instances de passerelle qui comptent chacune de leur côté, une limite de 100 par minute devient 100 par instance. Un stockage partagé comme Redis tient un seul compteur par client pour toutes les instances.

Choisissez un algorithme et écrivez-le. Une fenêtre fixe se réinitialise chaque minute et autorise des rafales à la frontière. Une fenêtre glissante lisse ce phénomène. Un seau à jetons (token bucket) autorise de courtes rafales jusqu'à une taille donnée tout en maintenant un débit moyen.

Répondez par un 429. La RFC 6585 définit 429 Too Many Requests. La réponse doit expliquer la situation et peut inclure Retry-After, que la RFC 9110 définit comme une date HTTP ou un nombre de secondes à attendre. La RFC 6585 ne dit pas comment le serveur identifie le client ni comment il compte les requêtes : cette partie relève de votre conception, alors mettez-la sur le diagramme. Un brouillon de l'IETF définit des champs d'en-tête standard RateLimit et RateLimit-Policy, mais au moment de la rédaction (octobre 2026), il s'agit encore d'un brouillon.

Décidez de ce qui se passe quand le stockage des compteurs tombe. Échouer en mode ouvert (fail open) garde l'API disponible sans limites ; échouer en mode fermé (fail closed) protège les services et rejette le trafic. Les deux peuvent être justes, pourvu que ce soit une décision et non un accident.

Les backends pour frontends

Le pattern Backends For Frontends de Sam Newman remplace un backend d'API généraliste par un composant côté serveur pour chaque expérience utilisateur. Chaque BFF est étroitement centré sur une seule interface et généralement maintenu par l'équipe qui construit cette interface, si bien que l'équipe peut faire évoluer l'API au rythme de ses écrans. Un backend partagé et généraliste tend à devenir un goulot d'étranglement, et l'article note que les services d'agrégation en bordure ont tendance à accumuler du code boursouflé.

Combien de BFF ? Newman attribue à Stewart Gleadow une règle simple : une expérience, un BFF. Si deux applications offrent la même expérience et qu'une seule équipe possède les deux, elles peuvent en partager un ; SoundCloud, par exemple, utilise un seul BFF pour ses applications d'écoute iOS et Android.

Les partenaires, c'est différent. Ils ont besoin d'une API stable et versionnée, pas d'une API taillée pour un écran ; leurs routes vont donc directement à l'API publique des services, sans BFF.

L'exemple : une boutique en ligne

La boutique a une application web React, des applications iOS et Android, et des partenaires qui créent des commandes via une API. Un WAF filtre le trafic avant la passerelle. La passerelle vérifie les jetons, compte les requêtes par client dans Redis et route selon le préfixe de chemin. Les équipes web et mobile possèdent chacune un BFF, et les deux BFF appellent les services Orders, Catalog et Accounts dans le réseau privé. Les appels des partenaires vont directement à l'API versionnée du service Orders.

Comment le lire :

• De gauche à droite, une requête. Un client appelle la passerelle à travers le WAF, et la passerelle route la requête vers un BFF ou vers l'API partenaire.
• Les liens en pointillé sont hors du chemin de la requête. L'application web se connecte auprès du fournisseur d'identité, et la passerelle récupère les clés de signature du fournisseur et les met en cache.
• Sous la passerelle, Redis contient les compteurs de limites de débit que partagent toutes les instances de la passerelle.
• Dans le réseau privé, chaque BFF n'appelle que les services dont ses écrans ont besoin.
• Le bloc Markdown est la politique de la passerelle : ce qu'elle vérifie, la limite et ce qu'elle laisse aux services.

Ce qu'il faut étiqueter

• Les routes de chaque backend, sous forme de préfixes de chemin ou d'hôtes.
• L'authentification à chaque entrée : le type de jeton, qui l'émet et ce que vérifie la passerelle.
• Les limites : la clé, le nombre et la fenêtre, et ce que le client reçoit en retour.
• Les délais d'expiration et les nouvelles tentatives à la passerelle. Les nouvelles tentatives en bordure multiplient la charge sur un service en difficulté.
• Le comportement en cas de panne quand le fournisseur d'identité, le stockage des compteurs ou un backend est indisponible.
• La responsabilité. L'équipe plateforme possède souvent la configuration de la passerelle ; les équipes d'interface possèdent leurs BFF.

Erreurs courantes

• De la logique métier dans la passerelle. Réécritures et conditions finissent en règles que personne ne peut tester. Gardez la passerelle légère.
• La passerelle comme seul contrôle de sécurité. Les services situés derrière ne devraient pas faire confiance à une requête simplement parce qu'elle est arrivée. Le diagramme d'architecture zero trust montre comment dessiner des contrôles à chaque saut.
• Des limites uniquement par IP, qui pénalisent les utilisateurs derrière des adresses partagées et ratent les clients qui changent d'adresse.
• Des compteurs locaux sur chaque instance, qui multiplient la limite par le nombre d'instances.
• Un seul BFF pour tout, ce qui redonne un backend généraliste.
• Un 429 sans détails. Les clients qui ne savent pas combien de temps attendre devinent, et ils devinent généralement trop court.

Pour ce qui se trouve derrière la passerelle, voir le diagramme d'architecture microservices. Sur Kubernetes, le diagramme Kubernetes Ingress couvre la couche qui se place souvent devant la passerelle ou en remplace certaines parties.

Le construire dans Archboard

1. Connectez-vous avec Google ou GitHub et créez un diagramme.
2. Depuis le pack Modèle C4, ajoutez un Conteneur pour l'application web et un autre pour l'application mobile, ainsi qu'un Système externe pour le partenaire.
3. Depuis le pack Sécurité, ajoutez un WAF et un Fournisseur d'identité.
4. Depuis le pack Cloud, ajoutez une Passerelle API, et depuis le pack Données un nœud Redis pour les compteurs de limites de débit.
5. Ajoutez un Cadre du pack Base nommé Private network, avec des nœuds Conteneur du pack Modèle C4 pour les deux BFF et les trois services.
6. Reliez-les de gauche à droite, étiquetez chaque route avec son chemin et dessinez en pointillé la connexion et la récupération des clés. Ajoutez un bloc Markdown du pack Base avec la politique de la passerelle.

L'exemple utilise 14 nœuds de diagramme et reste dans les limites de l'offre Free.

FAQ

Une passerelle API est-elle la même chose qu'un répartiteur de charge ? Non. Un répartiteur de charge distribue les requêtes entre les instances. Une passerelle comprend les requêtes d'API : les routes, les jetons et les quotas. Beaucoup de passerelles fonctionnent derrière un répartiteur de charge.

Ai-je besoin d'un service mesh si j'ai une passerelle API ? Ils résolvent des problèmes différents. La passerelle gère le trafic venant de l'extérieur ; un mesh gère les appels entre services, comme le TLS mutuel et les nouvelles tentatives. Dessinez-les séparément si vous utilisez les deux.

Les services doivent-ils valider le jeton si la passerelle l'a déjà fait ? Oui, pour les claims sur lesquels ils s'appuient. La passerelle rejette tôt les mauvais jetons, et chaque service autorise quand même l'action lui-même.

Combien de BFF faut-il ? Un par expérience utilisateur. Deux applications offrant la même expérience et possédées par la même équipe peuvent en partager un.

Que doit contenir une réponse 429 ? Une courte explication et un en-tête Retry-After indiquant le nombre de secondes à attendre, pour que les clients patientent au lieu de réessayer immédiatement.

Commencez gratuitement — un siège, sans carte bancaire.