Remplir un brief d’intégration avec une demande de rapport

Décrivez un projet d’intégration à travers un flux complet avant de comparer les offres. « Le portail a besoin d’une connexion API » ne précise ni les données transférées, ni le moment où le travail est terminé, ni qui traite les erreurs. Un brief complété permet de discuter de ces décisions.

Définir un flux pour la première livraison

Dans ce projet fictif, un portail demande un rapport PDF mensuel à un service documentaire. Tous les noms, champs et réponses sont nos propres exemples, pas l’API d’un fournisseur.

Cette distinction rend aussi les ajouts visibles : une future fonction d’e-mail constituerait une étape séparée, avec sa propre gestion des erreurs. Elle ne se dissimule pas dans le mot « connexion ».

Préciser les valeurs et le sens des entrées

Le contenu d’exemple suivant est convenu pour POST /report-jobs :

{"requestId":"R-52","projectId":"P-18","templateId":"monthly-v2","period":"2026-10"}

L’identifiant de requête désigne cette demande de création. Le projet et le modèle sont des références stables ; la période est ici un mois civil au format année–mois. Des noms d’affichage ou une période en texte libre ne remplacent pas ces valeurs. Le portail doit déterminer avec le service documentaire quels modèles sont approuvés.

L’accès au travail, à son état et au fichier est limité au projet autorisé. Connaître un lien ne suffit pas pour télécharger. Le brief précise les rôles et le mode d’accès ; les véritables jetons et mots de passe restent hors du document.

Décrire séparément l’acceptation et le résultat

Après enregistrement durable de la demande, le service d’exemple répond avec HTTP 202 et Location: /report-jobs/J-52 :

{"jobId":"J-52","status":"queued"}

MDN décrit 202 comme l’acceptation d’un traitement non terminé. Notre contrat prévoit donc les états queued (en attente), running (en cours), succeeded (réussi) et failed (échoué). Le travail réussit seulement lorsque le fichier est créé et accessible, au moment de l’achèvement, avec les autorisations requises. Microsoft décrit une consultation d’état séparée pour le travail asynchrone ; les noms d’état précis employés ici sont notre choix.

Le même identifiant de requête, avec un contenu identique dans le même périmètre autorisé, renvoie au même travail. Pour un contenu différent, l’exemple prévoit HTTP 409. Cette règle de répétition doit être implémentée et vérifiée ; le nom du champ ne crée pas à lui seul l’idempotence.

Renseigner quatre cas de recette avant l’implémentation

Dans le dernier cas, l’équipe plateforme vérifie le modèle. Une nouvelle demande corrigée reçoit un nouvel identifiant ; le travail échoué reste traçable. Si seule la consultation d’état est indisponible, le portail indique que l’état actuel est inconnu, sans affirmer une réussite ou un échec.

Résoudre les questions d’exploitation avant de s’engager

Complétez le volume de travaux attendu, la taille habituelle des fichiers, l’attente acceptable, l’intervalle de consultation et la conservation des fichiers et états selon l’usage réel. Ces valeurs restent ouvertes dans l’exemple et doivent être précisées avant un engagement fiable. Une durée estimée n’est pas assimilée à une propriété mesurée.

Une description OpenAPI peut préciser les opérations, les entrées et les réponses attendues. La définition métier du résultat et les responsabilités des équipes doivent aussi être établies. Les cas détaillés permettent ensuite aux équipes portail et plateforme d’évaluer la même livraison.

Sources

• MDN: 202 Accepted

• Microsoft: Asynchronous Request-Reply pattern

• OpenAPI Specification 3.1.1: Operation and Responses