Imaginez qu’un site de commande envoie une nouvelle commande à un système de gestion. Celui-ci l’enregistre, mais la confirmation n’arrive jamais au site. Le site doit-il réessayer ? Cela pourrait-il créer une deuxième commande ? Cette situation illustrative montre pourquoi un contrat d’API compte pour les opérations métier. Il décrit le comportement attendu de chaque côté, y compris les cas qu’une démonstration réussie ne révélera peut-être jamais.
Sur cette page
Partez du parcours métier et de la responsabilité sur les données
Cartographiez une interaction depuis l’action de l’utilisateur jusqu’à son résultat confirmé. Pour l’exemple de commande, identifiez qui crée la référence, quel système décide de son acceptation et où le client consulte son état. Distinguez une requête reçue d’une commande acceptée : il peut s’agir d’événements différents. Décidez également quel système peut modifier chaque information. Si les deux peuvent modifier une adresse de livraison, le contrat doit définir une règle de mise à jour, plutôt que supposer que le dernier écran contient la valeur de référence.
- Nommez le responsable des informations de commande, de client et de statut.
- Précisez le résultat que l’utilisateur doit voir immédiatement.
- Identifiez les mises à jour ultérieures que le système destinataire doit envoyer.
Rendez les définitions des champs concrètes
Pour chaque message, documentez les informations obligatoires, les valeurs autorisées et le sens d’une information absente. Un prix nécessite une devise et une interprétation claire ; un horodatage, une convention de fuseau horaire convenue. Utilisez une commande d’exemple réaliste pour discuter de ces règles. Demandez si « annulé » décrit toute la commande ou un seul article, et si une adresse vide signifie inconnue ou volontairement supprimée. Décrivez les enregistrements que chaque appelant est autorisé à lire ou modifier. Ces décisions influencent la spécification et l’expérience de l’application ; faire correspondre les noms de champs ne suffit pas à les trancher.
Précisez les requêtes répétées et les erreurs utiles
Pour la commande de l’exemple, une règle proposée pourrait être la suivante : pendant une durée de conservation convenue, renvoyer le même identifiant de requête avec des détails identiques retourne la référence de la commande existante. Réutiliser cet identifiant avec des détails différents produit un conflit à résoudre par l’appelant. Définissez explicitement le périmètre de l’identifiant et sa durée de conservation. Distinguez ensuite les erreurs à corriger des défaillances temporaires. Un dépassement de délai ne permet pas à lui seul de savoir si la commande a été enregistrée : l’appelant doit donc pouvoir vérifier le résultat avant de choisir l’étape suivante.
- Adresse de livraison manquante : retourner une explication au niveau du champ ; corriger la requête avant de la renvoyer.
- Résultat incertain : rechercher l’identifiant de requête et rapprocher son état enregistré.
- Défaillance temporaire du service : suivre la politique de nouvelle tentative convenue ; éviter de créer une nouvelle identité de commande à chaque essai.
Convenez des tests et des modifications du contrat
Demandez aux deux équipes de parcourir une commande réussie, une requête répétée, une adresse invalide et une confirmation interrompue. Vérifiez qu’elles attendent le même résultat dans chaque cas. Conservez ces exemples avec la spécification et utilisez-les lors des évolutions de l’intégration. Identifiez les responsables de l’approbation des changements, de l’information des équipes connectées et de l’analyse des incidents. Le transfert doit expliquer comment le support peut retracer une requête sans exposer inutilement des informations client, et comment un changement incompatible sera introduit auprès des consommateurs existants de l’API.