Guide d'utilisation du KongHttpService

Ce guide explique comment utiliser le nouveau KongHttpService pour standardiser les requêtes HTTP via KONG dans l'application Gestion Magasin.

Installation et Configuration

Le KongHttpService est automatiquement disponible dans toute l'application grâce au module global KongModule.

Variables d'environnement requises

KONG_API_GATEWAY=https://kong-proxy.staging.ubsi.fr
KONG_API_KEY=dev-kong-api-key-ubsi

Utilisation de base

1. Injection du service

import { Injectable } from '@nestjs/common';
import { KongHttpService } from '../kong/kong-http.service';

@Injectable()
export class YourService {
  constructor(private readonly kongHttpService: KongHttpService) {}
}

2. Requêtes simples

// GET simple
const response = await this.kongHttpService.get('/api/publique/produits');

// POST avec données
const response = await this.kongHttpService.post(
  '/api/publique/commandes',
  orderData
);

// PUT
const response = await this.kongHttpService.put('/api/magasins/1', storeData);

// DELETE
const response = await this.kongHttpService.delete('/api/produits/123');

3. Utilisation avec targetApp (optionnel)

Le paramètre targetApp est entièrement optionnel et n'a aucun impact fonctionnel. Il sert uniquement à aider les développeurs à identifier quelle application cible est appelée lors du debugging ou de la maintenance.

// Avec targetApp pour clarifier l'intention du développeur
const response = await this.kongHttpService.get('/api/publique/produits', {
  targetApp: 'referentiel', // Aide à comprendre qu'on appelle le service référentiel
});

const response = await this.kongHttpService.post(
  '/api/publique/commandes',
  orderData,
  {
    targetApp: 'ecommerce', // Indique qu'on appelle le service e-commerce
  }
);

4. Options avancées

// Avec headers personnalisés
const response = await this.kongHttpService.get('/api/private/data', {
  headers: {
    'X-Custom-Header': 'custom-value',
    Authorization: 'Bearer token',
  },
  timeout: 10000, // 10 secondes
});

// Avec headers ET targetApp pour documentation
const response = await this.kongHttpService.get('/api/private/data', {
  targetApp: 'referentiel', // Optionnel : aide à documenter l'intention
  headers: {
    'X-Custom-Header': 'custom-value',
  },
  timeout: 10000,
});

5. Utilisation avec des Observables (si nécessaire)

// Pour les cas où vous avez besoin de l'Observable RxJS
const observable = this.kongHttpService.get$('/api/publique/produits');

const response = await firstValueFrom(observable);

// Avec targetApp si souhaité pour documentation
const observable = this.kongHttpService.get$('/api/publique/produits', {
  targetApp: 'referentiel', // Optionnel : pour clarifier l'intention
});

6. Gestion des erreurs avec retry automatique

try {
  // Version simple sans targetApp
  const response = await this.kongHttpService.withRetry(
    () => this.kongHttpService.get('/api/unstable-endpoint'),
    3, // 3 tentatives maximum
    2000 // 2 secondes de délai entre les tentatives
  );

  // Avec targetApp pour documentation (optionnel)
  const response = await this.kongHttpService.withRetry(
    () =>
      this.kongHttpService.get('/api/unstable-endpoint', {
        targetApp: 'referentiel', // Aide à identifier l'app cible
      }),
    3,
    2000
  );
} catch (error) {
  this.logger.error('Failed after retries', error);
}

À propos du paramètre targetApp

Important : Le paramètre targetApp est entièrement optionnel et n'a aucun impact fonctionnel sur les requêtes HTTP.

Pourquoi existe-t-il ?

• Documentation du code : Aide les développeurs à comprendre quelle application est ciblée
• Debugging : Facilite l'identification des services appelés lors du débogage
• Maintenance : Améliore la lisibilité du code pour les futures modifications

Utilisation recommandée

• Privilégier la simplicité : Commencer par des appels sans targetApp
• Ajouter si nécessaire : Utiliser targetApp uniquement quand cela améliore la compréhension du code
• Pas obligatoire : Tous les appels fonctionnent parfaitement sans ce paramètre

Applications cibles disponibles (pour targetApp)

Voici la liste des valeurs possibles pour targetApp (si vous choisissez de l'utiliser) :

• achat
• bi
• ecommerce
• fidelite
• gestion
• logistique
• paiement
• promotion
• referentiel
• sav