API management et API gateways : politiques, rate limiting, plans et portails

Dès qu'une API a des consommateurs que vous ne maîtrisez pas, toute une série de préoccupations apparaît qui n'a rien à voir avec son comportement métier. Qui appelle ? En a-t-il le droit ? À quelle fréquence peut-il appeler ? Comment intégrer les cent prochains développeurs sans organiser une réunion pour chacun ? Quels endpoints sont réellement utilisés, par qui, et avec quelles performances ? Intégrer ces réponses dans chaque service, c'est les réécrire encore et encore, et de manière incohérente. Une API gateway les concentre en bordure ; une plateforme d'API management y ajoute la couche commerciale et organisationnelle.

La distinction compte au moment de choisir un outil, car le mot « gateway » recouvre des produits dont la complexité s'étale sur trois ordres de grandeur : d'une centaine de lignes de configuration de proxy à une suite complète avec portail, intégration de facturation et workflow de gouvernance. Ce guide sépare la fonction technique de la fonction de management, et s'attache à préciser quels problèmes justifient quelle dépense.

Ce qui se trouve sur le chemin de la requête

Quatre composants s'intercalent couramment entre un client et un service, et on les confond régulièrement.

Un load balancer raisonne en instances, pas en API ; il est incapable de voir que POST /transfers mérite une autre limite de débit que GET /rates. Un reverse proxy ajoute la connaissance des chemins, mais aucune notion d'identité de consommateur ni de quota. L'API gateway est le premier composant à comprendre qui appelle quelle opération dans le cadre de quel plan, et c'est ce qui rend les politiques possibles.

Le mesh se situe sur un autre axe. Les gateways traitent le trafic nord–sud, celui qui entre dans le système et en sort, tandis qu'un mesh gère le trafic est–ouest entre services internes. Ils se recoupent sur les retries et le mTLS mais sont complémentaires plutôt que concurrents : la plupart des plateformes équipées d'un mesh gardent une gateway en bordure, et nombre de systèmes ont besoin d'une gateway sans aucun mesh. Le compromis du mesh est approfondi dans les design patterns des microservices.

Ce qui distingue la gateway du bus de services d'entreprise, c'est l'intention. Les deux font de la médiation, mais le bus a été conçu pour héberger la logique d'intégration et a grossi jusqu'à contenir les règles métier de l'entreprise, alors qu'une gateway est volontairement maintenue mince. SOA et ESB raconte comment cela a mal tourné ; la leçon à retenir, c'est que toute décision métier prise dans la gateway est une décision que les tests de votre service ne voient pas.

Les politiques appliquées par la gateway

Le comportement d'une gateway s'exprime sous la forme d'une chaîne de politiques évaluées à chaque requête. La syntaxe exacte varie ; les catégories, non.

• Contrôle du trafic — limites de débit, quotas, plafonds de concurrence, taille maximale des requêtes, listes d'IP autorisées et refusées, circuit breaking vers un upstream défaillant.
• Sécurité — terminaison TLS, validation des clés d'API, introspection de jetons OAuth 2.0 ou vérification de signature JWT, TLS mutuel pour les partenaires, gestion de CORS, protection contre les injections et validation des payloads par rapport au schéma OpenAPI.
• Routage — routage par chemin, hôte ou en-tête, répartition pondérée pour les canary releases, upstreams versionnés, retries et timeouts.
• Médiation — manipulation d'en-têtes, adaptation de protocole, cache des réponses, compression.
• Observabilité — logs d'accès, métriques de latence et d'erreurs par opération et par consommateur, propagation de traces, injection d'identifiants de corrélation.

# Declarative gateway configuration: one route, several policies.
routes:
  - name: payments-v2
    match:
      host: api.example.com
      path: /v2/payments
    upstream: payments-service.internal:8080
    policies:
      - jwt:
          issuer: "https://login.example.com/"
          audiences: ["payments"]
          requiredScopes: ["payments:write"]
      - rateLimit:
          identifier: consumerId        # per API consumer, not per IP
          limit: 100
          window: 1m
          policy: sliding-window
      - requestSizeLimit: { maxBodyBytes: 65536 }
      - timeout: { upstream: 2s }
      - headers:
          remove: ["X-Internal-Debug"]
          add:    { "X-Correlation-Id": "${trace_id}" }

Versionnez cette configuration et déployez-la par le même pipeline que le code. Une gateway configurée à coups de clics dans une console est un système de production sans historique, sans revue et sans retour arrière.

Le rate limiting en pratique

Le rate limiting protège l'upstream contre la surcharge et protège les consommateurs les uns des autres. Quatre algorithmes couvrent presque tous les déploiements, et leurs différences se manifestent précisément quand le trafic arrive par rafales.

Fenêtre fixe. On compte les requêtes par minute d'horloge et on remet le compteur à zéro au changement de fenêtre. Simple à implémenter et peu coûteuse à stocker, avec un défaut sérieux : un client peut envoyer tout son quota dans la dernière seconde d'une fenêtre, puis à nouveau dans la première seconde de la suivante, soit le double du débit prévu à cheval sur ces deux fenêtres.

Fenêtre glissante. On approxime les 60 dernières secondes en pondérant la fenêtre fixe courante et la précédente, ou l'on conserve un journal des horodatages pour être exact. Cela supprime la rafale de changement de fenêtre pour un surcoût modeste ; c'est le choix par défaut raisonnable.

Token bucket. Un seau contient jusqu'à B jetons et se remplit à R jetons par seconde ; chaque requête consomme un jeton, et une requête qui n'en trouve pas est rejetée. On autorise ainsi des rafales jusqu'à la taille du seau tout en imposant un débit moyen, ce qui correspond au comportement réel des clients : un chargement de page qui déclenche huit requêtes parallèles ne doit pas être pénalisé si le client est par ailleurs calme.

Leaky bucket. Les requêtes sont mises en file et s'écoulent à débit constant, ce qui lisse entièrement la sortie. Utile devant un composant qui ne supporte vraiment pas les rafales, comme un backend legacy ou une API partenaire à la limite stricte, au prix d'une latence accrue pour les requêtes en file.

Trois détails déterminent si la limitation rend service ou exaspère. D'abord, la clé de limitation : limiter par adresse IP pénalise tous ceux qui sont derrière le NAT d'une entreprise et ne fait rien contre un appelant distribué ; utilisez le consommateur authentifié dès qu'il existe, et ne vous rabattez sur l'IP que pour le trafic anonyme. Ensuite, ce que vous renvoyez : un 429 accompagné de Retry-After et d'en-têtes indiquant la limite, le reliquat et l'heure de réinitialisation permet à un client bien élevé de ralentir correctement ; un 429 tout sec lui apprend à réessayer immédiatement. Enfin, l'état partagé : dans une gateway en cluster, les compteurs doivent être partagés, sinon la limite effective est multipliée par le nombre de nœuds.

Identité, clés et credentials

Trois mécanismes coexistent, et chacun répond à une question différente.

Les clés d'API identifient l'application appelante. Ce sont des secrets partagés transmis dans un en-tête, faciles à émettre et faciles à laisser fuiter, qui ne portent ni identité d'utilisateur ni expiration, sauf si vous en ajoutez une. Elles restent adaptées aux intégrations de serveur à serveur, aux données publiques en lecture seule et à la mesure de l'usage, à condition de ne circuler que sur TLS, d'être stockées sous forme de hash, limitées à des API précises et renouvelables sans interruption, ce qui suppose d'accepter deux clés actives par consommateur pendant une rotation.

Les jetons d'accès OAuth 2.0 portent une autorisation déléguée : quelle application, agissant pour quel utilisateur, avec quels scopes, jusqu'à quand. La gateway valide le jeton — signature, émetteur, audience, expiration — et transmet les claims vérifiés en aval, si bien que les services ne manipulent jamais de credentials bruts. C'est le bon choix par défaut dès que des utilisateurs finaux sont en jeu.

Le TLS mutuel authentifie le client par certificat au niveau transport ; il est courant pour les intégrations avec des partenaires ou dans la finance, là où une autorité de certification décide déjà qui peut se connecter.

Le découpage qui fonctionne : la gateway rejette tout ce qui est non authentifié ou malformé et transmet une identité vérifiée ; le service applique l'autorisation, car lui seul sait si ce client peut consulter ce compte. Une gateway ne peut pas prendre de décisions au niveau de l'enregistrement, et faire comme si c'était le cas crée un système où quiconque atteint un service bénéficie d'une confiance absolue — à une route mal configurée d'une fuite de données.

Ne laissez jamais les credentials aboutir là où ils sont conservés : retirez les en-têtes d'autorisation des logs d'accès et refusez les jetons ou les clés passés en query string, car ils finissent dans les logs des proxys et dans l'historique des navigateurs.

Produits, plans et portail développeur

Les plateformes de management ajoutent une couche d'abstraction au-dessus des routes techniques, et c'est elle qui permet à un programme d'API de passer à l'échelle sur le plan organisationnel.

Un produit d'API regroupe une ou plusieurs API en une offre à laquelle un consommateur s'abonne : « Payments » peut inclure l'API de paiements, l'API de mandats et le flux de webhooks. Un plan associe des conditions au produit : limites de débit, quotas mensuels, endpoints disponibles, niveau de support et prix. Les consommateurs enregistrent une application, l'abonnent à un plan et reçoivent des credentials limités en conséquence.

Cette structure vous donne le vocabulaire d'un accès différencié — un niveau gratuit à 1 000 appels par mois pour l'évaluation, un niveau standard pour la production, un niveau partenaire avec des limites plus élevées et un contrat de support — sans que rien de tout cela n'apparaisse dans le code des services.

Le portail développeur est la vitrine en libre-service : catalogue de produits, référence OpenAPI interactive, guides de démarrage, gestion des credentials, demandes d'abonnement, tableaux de bord d'usage et changelogs. Sa valeur se mesure au temps nécessaire pour réussir un premier appel. Un portail où un nouveau développeur peut s'inscrire, obtenir une clé de sandbox et recevoir une vraie réponse en dix minutes supprime une somme considérable de travail de support ; un portail où chaque credential exige un ticket n'en supprime aucune. Des environnements de sandbox avec des données de test réalistes comptent ici davantage que n'importe quelle fonctionnalité de gateway.

Les analytics bouclent la boucle : appels par opération, par consommateur et par version ; taux d'erreur et leurs causes ; percentiles de latence en bordure ; consommation des quotas à l'approche des limites. C'est ainsi que vous apprenez que la version 1 porte encore 40 % du trafic, issu de deux consommateurs : précisément la preuve dont une décision de retrait a besoin. C'est aussi, le cas échéant, la base d'une facturation à l'usage.

La gouvernance du cycle de vie relie l'ensemble : revue de conception au regard des standards avant publication, processus de dépréciation documenté avec l'en-tête Sunset et des annonces sur le portail, et un linter qui applique vos règles de conception d'API à chaque modification OpenAPI. Les contrôles automatisés dans le pipeline passent à l'échelle ; les comités de revue, non.

Topologies de déploiement

L'endroit où tourne la gateway conditionne la latence, le rayon d'impact des pannes et les personnes habilitées à la modifier.

Gateway de bordure centralisée. Un seul cluster devant tout le reste. C'est la plus simple à exploiter et à comprendre, avec une politique uniforme et un seul endroit où regarder. C'est aussi un point de défaillance unique et une ressource partagée derrière laquelle toutes les équipes font la queue ; elle exige donc une vraie planification de capacité et un chemin de configuration en libre-service.

Gateway par domaine ou par zone. Des gateways distinctes pour le trafic public, partenaire et interne, ou par domaine métier. Cela circonscrit le rayon d'impact, autorise des postures de politique différentes — le trafic interne a rarement besoin du même throttling que le trafic public — et rapproche la responsabilité de la configuration des équipes.

Micro-gateway ou sidecar. Une gateway légère déployée avec chaque service ou chaque équipe, configurée de façon centralisée. Elle supprime le goulet d'étranglement partagé, au prix des problèmes de cohérence qu'apporte un saut réseau de plus ; utile dans les grandes organisations qui ont dépassé le stade d'une bordure unique.

Gateway cloud managée. Le service du fournisseur cloud, intégré à sa gestion des identités, des logs et des certificats. Le moins de travail d'exploitation et le moins de portabilité, généralement facturé au million d'appels, ce qui devient significatif à fort volume.

Un modèle hybride est courant et raisonnable : une gateway managée pour le trafic public et un ingress controller dans le cluster pour le routage nord–sud interne. L'essentiel est que chaque gateway ait un responsable, un pipeline de configuration et un comportement en cas de panne documenté — en particulier, savoir si une panne de gateway laisse tout passer (fail open) ou bloque tout (fail closed), une décision à prendre délibérément plutôt qu'à découvrir.

Choisir une catégorie de produit

Le marché se divise en familles reconnaissables, et identifier celle dont vous avez besoin épargne beaucoup d'effort d'évaluation.

• Open source à base de proxy — un data plane rapide avec un modèle de plugins, auto-hébergé, les fonctions de management étant disponibles en extensions ou dans une offre payante. Intéressant si vous avez des ingénieurs plateforme et voulez maîtriser le coût et l'emplacement.
• Suites de gestion du cycle de vie complet — gateway, portail, analytics, monétisation et gouvernance dans un seul produit, souvent sous licence entreprise. Justifié si vous avez de nombreux consommateurs externes, des conditions commerciales et des obligations d'audit.
• Gateways des fournisseurs cloud — profondément intégrées, rapides à mettre en route, facturées à l'appel, les plus faibles en portabilité et en sophistication du portail.
• Ingress controllers et Kubernetes Gateway API — une gestion des routes exprimée sous forme de ressources Kubernetes. Excellents pour le routage interne et de plus en plus capables en bordure ; ce n'est pas une plateforme d'API management.

Évaluez au regard d'exigences que vous pouvez démontrer, pas de matrices de fonctionnalités. Les questions qui font la différence : comment la configuration est-elle versionnée et promue d'un environnement à l'autre ; quelle latence ajoutée au p99 avec votre profil de trafic ; comment les compteurs de rate limiting sont-ils partagés entre les nœuds ; que devient le trafic quand le control plane est indisponible ; le portail peut-il être personnalisé à vos couleurs et la documentation publiée automatiquement à partir de vos documents OpenAPI ; et combien cela coûte-t-il à dix fois le volume actuel. Concevez d'abord une bonne API — voir la conception d'API REST — car aucune gateway ne compense un contrat que les consommateurs ne peuvent pas utiliser.

Points clés à retenir

• La gateway est le premier composant du chemin qui comprend les consommateurs, les opérations et les plans ; les load balancers et les proxys n'en sont pas capables, et un mesh résout la moitié interne du problème.
• Gardez la gateway mince : politiques, routage et médiation y ont leur place, la logique métier non, sinon vous reconstruisez l'ESB.
• Choisissez l'algorithme de rate limiting selon le profil du trafic, limitez par consommateur authentifié plutôt que par adresse IP, et renvoyez un 429 avec Retry-After et des en-têtes de limite.
• Laissez la gateway authentifier et le service autoriser ; une gateway ne peut pas prendre de décisions d'accès au niveau de l'enregistrement.
• Les produits, les plans et un portail en libre-service doté d'une sandbox permettent à un programme d'API de dépasser la poignée de consommateurs, et les analytics par version rendent les décisions de retrait défendables.
• Choisissez la topologie et la catégorie de produit à partir d'exigences démontrables : configuration as code, latence ajoutée, compteurs partagés, comportement en cas de panne du control plane et coût à grande échelle.