API passerelle et routage

1) Rôle de la passerelle API dans l'architecture

• Recevoir le trafic entrant (HTTP/HTTP2/HTTP3, WebSocket, gRPC) ;
• route selon les règles (host/path/headers/method/query/geo/poids/health) ;
• applique des politiques de bout en bout : authentification/autorisation, limitation des taux, WAF, CORS, cache ;
• effectue des transformations (normalisation des en-têtes/corps, gRPC↔JSON, stitching GraphQL) ;
• assure la résilience (timeouts, retries, circuit-breaker, outler detection) ;
• donne l'observabilité et la facturation (logs, métriques, tracés, quotas) ;
• isole la topologie interne (service mesh, services privés).

Souvent utilisé dans la paire : Edge/API-Gateway + Ingress/Mesh (Envoy/Istio/Linkerd) - le premier décide de la politique étrangère, le second est east-west.

2) Topologies types

Une seule passerelle globale (CDN/edge POP → L7 gateway → services) est simplement une stratégie centralisée.
Passerelles régionales (par région) + routage intelligent par géo/latence.
Multi-tenant : itinéraires/sous-domaines/clés dédiés, quotas et limites par locataire.
Hybrid : on-bou + cloud, lien privé/peering, backends privés derrière la passerelle API.

3) Règles de routage L7

• Host/Path: `api. example. com` → `/v1/orders/`.
• Headers: `X-Client`, `X-Region`, `User-Agent`, `Accept`.
• Method/Content-Type : distinction JSON/Proto/GraphQL.
• Query/Fragment : prudent - affecte le cache/options.
• Géo/Latency : RR/région la plus proche, défaillance en cas de dégradation.
• Weighted/Canary : distribution du trafic 90/10, 50/50, sticky par cookie.
• Session affinity : hash-based par clé/token (soigneusement lors de la mise à l'échelle).

yaml nginx. ingress. kubernetes. io/canary: "true"
nginx. ingress. kubernetes. io/canary-weight: "10" # 10% traffic to new backend

yaml match: { prefix: "/orders", headers: [{name: "X-Experiment", exact_match: "new"}] }
route: { cluster: orders-v2 }

4) Protocoles et interopérabilité

REST/JSON est un défaut, décrivez OpenAPI pour la validation/génération de clients.
gRPC - Proto binaire au-dessus du HTTP/2 ; pour les clients externes, utilisez gRPC-JSON transcoding.
GraphQL - agrégation des services ; sur le périmètre, surveiller la complexité/profondeur des requêtes.
WebSocket/SSE - bidirectionnel/push ; tenez compte du sticky et des timeouts.
HTTP/2/3 (QUIC) - multiplexage/démarrage rapide ; vérifier la compatibilité avec WAF/proxy.

5) Sécurité : Authentification et autorisation

5. 1 Transport

TLS 1. 2 + sur le périmètre, HSTS, stapling OCSP, PFS.
mTLS pour les API B2V/internes et les machines-k-machine.
IP allowlist/denylist, géo-restrictions.

5. 2 Niveau d'application

OAuth2/OIDC : jetons bearer JWT, validation signature/expedition/audience.
NMAS/signatures : Date + chaîne canonisée + signature (comme AWS) : Protection contre la substitution, la répétition (nonce/fenêtre temporelle).
Clés API : uniquement en tant qu'identifiant ; droits - via RBAC/ABAC/scoops.
CORS : allow-origin explicite, pré-flyte cache.
WAF : signatures (OWASP API Top 10), anormalie, bot defense, champs JSON récursifs.
DDoS/Abuse : connection limiting, token-bucket/Leaky bucket, burst + vitesse moyenne, bancs dynamiques.

yaml plugins:
- name: oidc config: { issuer: "...", client_id: "...", client_secret: "...", scopes: ["orders. read"] }
- name: rate-limiting config: { minute: 600, policy: local }

6) Validation, transformation et interopérabilité

Schémas : validation du corps/en-têtes/paramètres par OpenAPI/JSON-Schema/Protobuf.
Transformations : normalisation des champs, masquage PII, ajout d'en-têtes de corrélation ("traceparent", "x-request-id').
Versioning : 'Header : X-API-Version', préfixes '/v1 ', ressource-versioning ; deprecation policy и Sunset.
Backward-compat : uniquement le champ add ; éviter les changements « cassants » sans nouvelle version.
Idempotency: `Idempotency-Key` для POST; gateway stocke les clés dans Redis avec TTL.

7) Durabilité : politiques de connexion

Timeouts: connect/read/write; des défauts raisonnables (par exemple 1s/5s/5s).
Retries : seulement pour la sécurité et idempotent ; jitter, backoff exponentiel, maximum de tentatives.
Circuit breaker : ouvrir en cas d'erreur/latence ; half-open pour les échantillons.
Détection Outlier : sortir les mauvaises instances du pool.
Bulkhead/concurrence : limites pour les demandes simultanées par route.
Failover : actif/passif, dégradation zonale.
Shadow traffic : V2 « gris » en parallèle à V1 (sans effet sur la réponse) pour comparaison.

yaml circuit_breakers:
thresholds:
- priority: DEFAULT max_connections: 1024 max_pending_requests: 2048 max_retries: 3

8) Cache et performance

HTTP-кеш: `Cache-Control`, `ETag/If-None-Match`, `Vary`, `stale-while-revalidate`.
Edge-Keshi/RR : CDN pour les API statiques et les API « hachables » (idempotent GET).
Compression : 'gzip/br' (ne pas compresser déjà compressé).
Request collapsing (« coalescing ») : combine des requêtes parallèles identiques.
Réponse shaping : champs/filtres, pagination (cursor-based), limites de taille.

9) Observabilité et exploitation

Метрики: `l7_req_total{route,method,code}`, `latency_ms{p50,p95,p99}`, `upstream_errors`, `retry_count`, `cb_state`, `429_rate`, `quota_usage{tenant}`.
Logs : structural, avec 'trace _ id/span _ id', 'user _ id/tenant _ id', 'client _ ip'.
Tracks : W3C Trace Context (« traceparent », « tracestate »), faire de la propagande dans les apstrymes.
Audit : qui a appelé quoi, avec quels droits ; stockage immuable pour les API sensibles.
SLO/SLA : cible p99, budget des erreurs ; le routage est meilleur que le niveau mondial.

10) Gestion du plan de bande passante

Quota per-tenant/clé/pool de clients, en min/heure/jour.
Les limites de Burst + sustained ; leaky bucket pour lisser.
Fairness : en cas de surcharge, fair queuing au lieu du « premier rencontré ».
Priorités : itinéraires système/critique avec priorité et pools dédiés.

11) Gestion des changements et des versions

Canary/Blue-Green : routage de poids ; promotion automatique par SLO (erreurs/latence).
Fonctionnalité gates/drapeaux backend : activation par titre/token.
Shadowing/diff validators : comparaison des corps/statuts, tolérances delta.
Stagings : domaines/chemins dédiés ('staging. api... '), clés individuelles et quotas.

12) Exemples de configurations

12. 1 NGINX - gateway de base avec limite et cache

nginx map $http_x_request_id $reqid { default $request_id; }

limit_req_zone $binary_remote_addr zone=perip:10m rate=10r/s;

server {
listen 443 ssl http2;
server_name api. example. com;

security add_header Strict-Transport-Security "max-age = 31536000" always;

location /v1/ {
limit_req zone=perip burst=30 nodelay;
proxy_set_header X-Request-ID $reqid;
proxy_set_header Authorization $http_authorization;
proxy_connect_timeout 1s;
proxy_read_timeout 5s;

proxy_cache api_cache;
proxy_cache_valid 200 10s;
proxy_cache_use_stale error timeout updating;
proxy_pass http://orders-v1;
}
}

12. 2 Envoy - routage par poids et rétraction

yaml routes:
- match: { prefix: "/orders" }
route:
weighted_clusters:
clusters:
- name: orders-v1 weight: 90
- name: orders-v2 weight: 10 retry_policy:
retry_on: "5xx,reset,connect-failure"
num_retries: 2 per_try_timeout: 2s

12. 3 Traefik - Middlvari et headers

yaml http:
middlewares:
secHeaders:
headers:
stsSeconds: 31536000 contentTypeNosniff: true routers:
api:
rule: "Host(`api. example. com`) && PathPrefix(`/v1`)"
service: svc-orders middlewares: ["secHeaders"]

13) Anti-modèles

Une limite mondiale pour tous - les « bons voisins » souffrent de « bruyants ».
Retrai sans idempotence → prise d'effets (paiements, création d'entités).
Ignorer 'timeout '/' max body size' → accrocher/épuiser les workers.
Mélanger les politiques edge et la logique d'entreprise dans la passerelle (alourdir le périmètre).
L'absence de validation des schémas → la fragilité des clients et les rejets « cassants ».
WebSocket nu sans tenir compte de l'auth/limites/idle-time.
Secrets dans les titres sans rotation ; l'absence de mTLS dans les B2B internes.

14) Test-playbooks (Game Days)

Tempête de demandes : vérification de limiteur/quota, comportement 429, dégradation.
Perte d'un seul cluster : échec/redistribution du poids ; SLO Canaries.
Réponses lourdes : max body/timeouts ; coupure des joints.
Injections/anomalies : règles WAF, interdiction des JSON récursifs, grandes profondeurs de GraphQL.
Échec de la trace : vérification de la propagande « traceparent » et de l'échantillonnage.
Secrets : rotation des clés/JWKS, expiration des tokens, tolérance clock-skew.

15) Chèque de mise en œuvre

• Domaines/chemins/versions définis, publié par OpenAPI/Proto.
• TLS/mTLS, HSTS, gestion des secrets et rotation sont configurés.
• Authentification incluse (OIDC/HMAC), RBAC/scoops, CORS.
• Limites/quotas per-tenant, files d'attente justes, 429-UX.
• Routage par poids/titre, plan Canaries et rollback.
• Politiques timeout/retry/circuit-breaker/outlier.
• Validation des schémas, transformations, masquage des IPI.
• Edge-кеш/ETag, coalescing, gzip/br.
• Observabilité : métriques, logs, pistes, dashboards et alertes.
• Runbooks : incidents, rotation des clés, feuilles de blocs, « Black Friday ».

16) FAQ

Q : En quoi la passerelle API diffère-t-elle du service mesh ?
R : La passerelle est nord-sud (périmètre extérieur, politiques de bout en bout). Mesh - est-ouest (liaison intraoclaster/MTLS/retrai). Souvent utilisés ensemble.

Q : Où mettre en œuvre auth : dans la passerelle ou les services ?
R : Les deux niveaux : la passerelle est coarse-grained (authentification, droits de base/quotas), le service est fine-grained (rôles de domaine/attributs).

Q : Quand avez-vous besoin de gRPC-JSON transcoding ?
R : Lorsque le gRPC interne et l'extérieur nécessite REST/JSON et des clients/navigateurs simples.

Q : Comment choisir une stratégie de versioning ?
R : Pour les API publiques, le chemin '/vN '+ les titres de privation et le long overlap. Pour l'intérieur - capability flags/schéma de compatibilité.

17) Résultats

La passerelle API n'est pas seulement « proxique », mais le centre des politiques et de la résilience. Le bon routage, la sécurité, les limites, la validation et l'observabilité donnent la prévisibilité et la vitesse de sortie. Combinez la passerelle edge avec le service mesh, automatisez les canaries et les quotas, testez les pannes - et le périmètre deviendra votre accélérateur plutôt qu'un goulot de bouteille.