Cloud et automatisation

Concevoir un moteur de rapports pour les consommateurs d’interface et d’API

Concevez un backend de rapports unique et gouverné pour les pages d’interface interactives, les API externes, les téléchargements et les gros exports asynchrones.

Par JaviPublié 9 min de lectureIntermédiaire

Des clients Web, mobiles et API externes qui partagent un même moteur de rapports

La plupart des plateformes de rapports finissent par avoir deux types de consommateurs : des personnes qui utilisent une interface Web ou mobile, et des systèmes qui appellent une API. Les deux veulent les mêmes chiffres métier, mais sous une forme différente. L’objectif de conception est un moteur de rapports unique qui porte la logique de chaque rapport une seule fois et n’adapte que la livraison à chaque consommateur.

Un seul backend

Dans la mesure du possible, les consommateurs d’interface et d’API utilisent le même moteur de rapports. Le parcours interactif va de l’interface à l’API, puis au moteur de rapports, et aboutit à du JSON ou à des données de page. L’export va de l’interface ou de l’API à une demande de rapport, à un CSV ou fichier généré et à une URL de téléchargement protégée. Partager la validation et l’autorisation évite que l’interface et l’API développent des règles de données contradictoires.

Logique de rapport partagée

La définition du rapport appartient au moteur, pas à l’un des consommateurs : dimensions et filtres autorisés, modèle de requête approuvé, règles de période, limites de lignes et signification de chaque mesure. L’interface comme l’API envoient leur intention à cette définition. Si l’application Web calcule ses propres totaux ou applique ses propres filtres, l’interface et l’API finiront par ne plus s’accorder sur le même rapport.

Évitez les implémentations dupliquées d’un même rapport, par exemple une requête pour le tableau de bord et une autre pour le point de terminaison d’export. Les doublons divergent : la correction d’un filtre ou d’une mesure arrive dans un chemin et pas dans l’autre, et les consommateurs obtiennent des réponses différentes à la même question. Une seule définition assortie de plusieurs contrats de livraison est plus facile à tester, à sécuriser et à faire évoluer.

Contrats par consommateur

Les écrans interactifs ont besoin de pagination, d’un tri stable, de projections compactes, d’annulation et d’une latence prévisible. Les exports ont besoin d’un choix de format, de limites plus larges, d’une exécution asynchrone, de stockage, d’expiration et d’une autorisation de téléchargement. La même définition logique du rapport peut servir les deux avec des contrats de livraison différents.

Besoin Consommateur d’interface Consommateur d’API
Forme de la réponse Page JSON compacte limitée aux colonnes affichées Schéma complet et documenté
Taille Petites pages pour un écran Pages plus grandes ou export vers un fichier
Latence Assez rapide pour une vue interactive Peut attendre la fin d’une exécution asynchrone
Formats JSON ou données de page JSON, CSV ou autre format de fichier autorisé
Durée de vie Abandonnée quand l’utilisateur quitte la page Résultat stocké avec expiration et lien de téléchargement

Pagination et tri

La pagination garde les réponses interactives petites et bornées. Chaque page doit provenir d’un tri stable, afin que la même demande renvoie les mêmes lignes dans le même ordre ; ajoutez une clé unique comme dernière colonne de tri lorsque la colonne visible comporte des égalités. Acceptez les champs de tri depuis une liste autorisée, comme pour les dimensions et les filtres, plutôt que de transmettre à une requête un nom de colonne fourni par le client.

Les consommateurs d’API ont souvent besoin du résultat complet plutôt que d’un seul écran. Proposez-leur des pages plus grandes avec le même tri stable, ou un export, plutôt que de les laisser parcourir des milliers de petites pages conçues pour l’interface.

Validation

Convertissez les valeurs d’affichage comme Date, Canal ou Compte en un enum de valeurs autorisées. Validez les dates de début et de fin, la période maximale, les filtres autorisés, l’accès au tenant, le format et les limites de lignes. Le client envoie une intention, jamais des fragments de requête. Le backend utilise des instructions paramétrées ou des générateurs de requêtes contrôlés.

Frontières d’authentification et d’autorisation

Les utilisateurs de l’interface et les clients d’API s’authentifient différemment : un utilisateur interactif se connecte, tandis qu’une intégration présente une identité de client ou une clé d’API. Les deux doivent aboutir à la même décision d’autorisation dans le moteur : à quel tenant appartient l’appelant, quels rapports il peut exécuter et quels filtres il peut appliquer. Déduisez l’identité du tenant des claims authentifiés ou d’une correspondance de service approuvée, jamais d’un tenant_id fourni par le navigateur ou l’appelant.

Les URL de téléchargement des résultats stockés ont une durée de vie courte et sont vérifiées par rapport au tenant demandeur. Consignez un événement d’audit pour chaque accès à un rapport et gardez les secrets et les valeurs de filtres sensibles hors des journaux ordinaires.

Réutilisation du cache

Comme les deux consommateurs appellent le même moteur, ils peuvent partager les résultats en cache. Construisez la clé de cache à partir de l’identité fiable du tenant, du type de rapport, des paramètres normalisés, du format et de la version du rapport, afin que la même demande logique, qu’elle vienne de l’interface ou de l’API, aboutisse à la même entrée. Incluez l’identité du tenant dans chaque clé et autorisez un résultat trouvé en cache avec la même rigueur qu’une nouvelle requête. La pagination et le tri modifient ce que renvoie une page : incluez-les dans la clé si vous mettez des pages en cache, ou mettez en cache le résultat complet et paginez à partir de celui-ci.

Limites de débit

Appliquez les limites par consommateur à partir de l’identité authentifiée : une rafale d’appels d’une intégration ne doit pas ralentir tous les utilisateurs interactifs. Les pages interactives et les gros exports méritent aussi des budgets distincts, car un export peut coûter autant que de nombreux affichages de pages. Renvoyez une réponse de limitation explicite, accompagnée d’indications, plutôt que de laisser les demandes dépasser leur délai, et orientez le travail lourd vers l’option asynchrone décrite ci-dessous. Mesurer le volume de requêtes API et de rapports explique comment réunir les éléments nécessaires pour fixer ces limites.

Option asynchrone

Pour les traitements volumineux, POST /reports peut renvoyer 202 Accepted avec un reportRequestId. GET /reports/{id} renvoie le statut, et GET /reports/{id}/download renvoie un résultat autorisé de courte durée. Les demandes petites et bornées peuvent rester synchrones ; faire passer chaque interaction par une file de traitements ajoute une complexité inutile.

Compromis et modes de défaillance

Des demandes plus flexibles sont plus utiles, mais élargissent la surface de sécurité et de performance. Pour chaque consommateur, privilégiez des contrats de rapport explicites et des variations autorisées plutôt qu’une interface de requête sans restriction. Davantage de cache réduit la charge de requêtes, mais crée des questions de fraîcheur et d’invalidation dont héritent les deux consommateurs.

Tenez compte des réussites partielles : un rapport peut se terminer après la déconnexion de l’appelant, et une écriture en cache peut échouer après le renvoi d’un résultat valide. Modélisez explicitement ces cas et ne laissez pas une sortie partielle passer pour un export complet.

Questions pour la revue opérationnelle

Avant la mise en production, confirmez que l’interface et l’API produisent des chiffres identiques pour le même rapport et les mêmes paramètres, que les deux chemins passent par la même validation et la même autorisation, et qu’un ID de demande relie l’écran d’un utilisateur ou un appel d’API à l’exécution correspondante. Vérifiez que les limites produisent des réponses explicites pour les deux consommateurs, que les exports expirent comme prévu et qu’une modification de la définition d’un rapport atteint tous les consommateurs en même temps. Qu’est-ce qu’un moteur de rapports ? et Architecture d’un moteur de rapports : de la demande au résultat complètent la série.

Étiquettes

  • Architecture de données
  • API
  • Rapports
  • CSV
  • Mise en cache
  • Multi-locataire