Modèles de passerelle API et meilleures pratiques pour les applications modernes

Les passerelles API gèrent en moyenne 83 % de tout le trafic d'entreprise, servant de point d'entrée unique pour les applications clientes. Une passerelle API bien conçue simplifie la communication client-serveur, applique les politiques de sécurité et assure l'observabilité sur tous les services. Un système mal conçu devient un goulot d’étranglement et un point de défaillance unique.

Ce guide couvre les modèles d'architecture de passerelle API, la sélection de technologies et les meilleures pratiques de mise en œuvre pour les applications Web, les systèmes ERP et les plateformes de commerce électronique.

Points clés à retenir

• Les passerelles API centralisent les préoccupations transversales (authentification, limitation de débit, journalisation) pour éliminer la duplication entre les services
• La limitation du débit au niveau de la passerelle protège les services backend des pics de trafic et des abus
• Les modèles de disjoncteurs empêchent les pannes en cascade lorsque les services en aval ne sont pas sains.
• Le versioning de l'API via la passerelle permet une évolution rétrocompatible de votre surface API

---

Modèles de passerelle principaux

Modèle 1 : routage des demandes

La passerelle achemine les requêtes vers le service backend approprié en fonction du chemin de l'URL, des en-têtes ou d'autres attributs de requête.

# Nginx as API gateway
upstream api_service {
    server api-1:3001;
    server api-2:3001;
}

upstream auth_service {
    server auth:9000;
}

upstream web_service {
    server web:3000;
}

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

    location /api/v1/ {
        proxy_pass http://api_service;
    }

    location /auth/ {
        proxy_pass http://auth_service;
    }

    location / {
        proxy_pass http://web_service;
    }
}

Modèle 2 : Authentification et autorisation

Centralisez l’authentification au niveau de la passerelle pour éviter de la mettre en œuvre dans chaque service.

// NestJS middleware for JWT validation at the gateway level
@Injectable()
export class GatewayAuthMiddleware implements NestMiddleware {
  constructor(private readonly jwtService: JwtService) {}

  async use(req: Request, res: Response, next: NextFunction) {
    // Skip public endpoints
    if (this.isPublicEndpoint(req.path)) {
      return next();
    }

    const token = this.extractToken(req);
    if (!token) {
      throw new UnauthorizedException('Missing authentication token');
    }

    try {
      const payload = await this.jwtService.verifyAsync(token);
      req['user'] = payload;
      next();
    } catch {
      throw new UnauthorizedException('Invalid token');
    }
  }

  private extractToken(req: Request): string | undefined {
    // Check cookie first, then Authorization header
    return req.cookies?.ecosire_auth
      || req.headers.authorization?.replace('Bearer ', '');
  }

  private isPublicEndpoint(path: string): boolean {
    const publicPaths = ['/health', '/api/v1/products', '/api/v1/blog'];
    return publicPaths.some(p => path.startsWith(p));
  }
}

Modèle 3 : Limitation du débit

// Rate limiting configuration per endpoint type
const rateLimits = {
  public: { windowMs: 60000, max: 100 },     // 100 req/min for public APIs
  authenticated: { windowMs: 60000, max: 500 }, // 500 req/min for authenticated users
  admin: { windowMs: 60000, max: 1000 },       // 1000 req/min for admin
  webhooks: { windowMs: 60000, max: 50 },       // 50 req/min for webhooks
};

Modèle 4 : Disjoncteur

Lorsqu'un service en aval tombe en panne, le disjoncteur empêche les pannes en cascade :

[Closed] --> (failures exceed threshold) --> [Open] --> (timeout expires) --> [Half-Open]
    ^                                                                            |
    |                                        (success)                           |
    +--------------------------------------------------------------------<-------+
    |                                        (failure)                           |
    |                                           +-------->  [Open]

États :

• Fermé : Les demandes transitent normalement. Suivez le nombre d’échecs.
• Ouvrir : toutes les demandes échouent immédiatement sans appeler le service. Renvoie la réponse mise en cache/de repli.
• Semi-ouvert : autorisez le passage d'une seule demande. Si cela réussit, fermez le circuit. En cas d'échec, rouvrez.

Modèle 5 : mise en cache des réponses

# Cache GET responses for public endpoints
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=api_cache:10m max_size=1g inactive=60m;

location /api/v1/products {
    proxy_pass http://api_service;
    proxy_cache api_cache;
    proxy_cache_valid 200 5m;
    proxy_cache_valid 404 1m;
    proxy_cache_key "$scheme$request_method$host$request_uri";
    add_header X-Cache-Status $upstream_cache_status;
}

---

## Stratégies de gestion des versions d'API

Recommandation : gestion des versions du chemin d'URL. C'est le plus explicite, le plus déboguable et le plus facile à router au niveau de la passerelle.

Modifications avec ou sans rupture

---

Comparaison des technologies de passerelle

Pour la plupart des PME : Nginx est suffisant. Il gère le routage, la terminaison SSL, la limitation de débit et la mise en cache avec une surcharge inférieure à la milliseconde. Passez à Kong lorsque vous avez besoin de fonctionnalités avancées de plug-in (OAuth2, transformation de requêtes, analyses).

---

Observabilité à la passerelle

Journalisation des demandes

log_format gateway '$remote_addr - $remote_user [$time_local] '
                   '"$request" $status $body_bytes_sent '
                   '"$http_referer" "$http_user_agent" '
                   '$request_time $upstream_response_time '
                   '$http_x_request_id';

access_log /var/log/nginx/gateway.log gateway;

Collecte de métriques

Suivez ces métriques au niveau de la passerelle :

• Taux de requête par point de terminaison, méthode et code d'état
• Distribution de latence (P50, P95, P99) par point de terminaison
• Taux d'erreur par point de terminaison et type d'erreur
• Taux d'atteinte de la limite par client
• Taux de réussite du cache par point de terminaison
• Temps de réponse en amont par rapport au temps de réponse total

---

Gestion des erreurs au niveau de la passerelle

Réponses d'erreur cohérentes

La passerelle doit normaliser les réponses d'erreur des différents services backend :

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "The requested service is temporarily unavailable",
    "requestId": "req_abc123",
    "timestamp": "2026-03-16T14:32:01Z"
  }
}

Nouvelle tentative et configuration du délai d'attente

location /api/ {
    proxy_pass http://api_service;

    # Timeout configuration
    proxy_connect_timeout 5s;
    proxy_send_timeout 30s;
    proxy_read_timeout 30s;

    # Retry on connection errors only (not on 5xx)
    proxy_next_upstream error timeout;
    proxy_next_upstream_tries 2;

    # Custom error pages
    error_page 502 503 504 /api-error.json;
}

Dégradation gracieuse

Lorsqu'un service backend non critique est en panne, la passerelle peut fournir des réponses mises en cache ou des données de secours au lieu de renvoyer des erreurs :

---

Modèles de sécurité de passerelle

Validation de la demande

Validez la structure de la demande avant de la transmettre aux services backend :

• Rejeter les demandes avec des types de contenu inconnus
• Appliquer la taille maximale du corps de la requête par point de terminaison
• Valider les en-têtes requis (version API, type de contenu)
• Supprimer les en-têtes suspects (en-têtes saut par saut, en-têtes internes au serveur)

Liste d'autorisation IP pour les points de terminaison d'administrateur

location /api/admin/ {
    allow 203.0.113.0/24;  # Office IP range
    allow 10.0.0.0/8;      # Internal network
    deny all;

    proxy_pass http://api_service;
}

Demander une transformation

La passerelle peut ajouter, modifier ou supprimer des en-têtes avant de transférer :

location /api/ {
    proxy_pass http://api_service;

    # Add security headers
    proxy_set_header X-Request-ID $request_id;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Real-IP $remote_addr;

    # Remove internal headers from responses
    proxy_hide_header X-Powered-By;
    proxy_hide_header Server;
}

---

Questions fréquemment posées

Avons-nous besoin d'une passerelle API pour une application monolithique ?

Oui, mais en plus simple. Même pour un monolithe, Nginx, en tant que proxy inverse, fournit une terminaison SSL, une limitation de débit, un service de fichiers statiques et des en-têtes de sécurité. Vous n'avez pas besoin de Kong ou d'AWS API Gateway pour un monolithe, mais vous avez besoin de quelque chose entre Internet et votre serveur d'applications.

Comment gérer le basculement de la passerelle API ?

Exécutez plusieurs instances de passerelle derrière un équilibreur de charge cloud (AWS ALB, Cloudflare). Si une instance de passerelle échoue, l'équilibreur de charge achemine le trafic vers des instances saines. Pour Nginx, utilisez des vérifications de santé actives et la suppression automatique des amonts défectueux.

La passerelle API doit-elle gérer l'authentification ou chaque service doit-il gérer ?

La passerelle doit gérer l'authentification (vérifier que le jeton est valide). Les services individuels doivent gérer l'autorisation (en vérifiant si l'utilisateur authentifié a l'autorisation pour l'action spécifique). Cette séparation maintient la passerelle légère et permet aux services de prendre des décisions précises en matière de contrôle d'accès.

Comment gérer CORS au niveau de la passerelle API ?

Configurez CORS au niveau de la passerelle pour éviter la duplication des en-têtes CORS entre les services. Définissez Access-Control-Allow-Origin sur vos domaines frontaux spécifiques (n'utilisez jamais * en production avec des informations d'identification). Gérez les requêtes OPTIONS de contrôle en amont au niveau de la passerelle pour réduire la charge sur les services backend.

---

Ce qui vient ensuite

Une passerelle API est la porte d’entrée de votre infrastructure. Associez-le à la surveillance pour la visibilité, au renforcement de la sécurité pour la protection et aux tests de charge pour la planification des capacités.

Contactez ECOSIRE pour des conseils en architecture d'API, ou explorez notre guide DevOps pour obtenir la feuille de route complète de l'infrastructure.

---

Publié par ECOSIRE – aide les entreprises à créer une infrastructure API évolutive.