Préparez une API partenaire exploitable : champs échangés, erreurs, pagination, droits d’accès et règles de version pour limiter les malentendus techniques.
Un partenaire sait qu’il doit envoyer une commande, mais plusieurs questions restent ouvertes. Un montant est-il exprimé en dirhams ou en centimes ? Une date correspond-elle à l’heure locale ? Une réponse positive confirme-t-elle la réception ou la création définitive ? Ces différences peuvent produire des erreurs même lorsque les deux applications communiquent correctement.
La spécification d’API doit décrire le contrat observable entre les systèmes. Elle permet aux équipes de préparer leurs échanges sans interpréter le code de l’autre application. Les décisions métier qui influencent les données doivent y apparaître clairement.
Définir les opérations et leur résultat
Commencez par les besoins du partenaire : créer une demande, consulter son état ou récupérer les changements récents. Pour chaque opération, indiquez qui l’utilise et quel résultat elle garantit. Évitez de reproduire toutes les tables internes de l’application simplement parce qu’elles existent.
Dans un exemple fictif, une demande reçue passe d’abord par une validation humaine. L’API doit distinguer l’accusé de réception du statut accepté. Le partenaire pourra ainsi informer son utilisateur sans annoncer une validation qui n’a pas eu lieu.
OpenAPI, ici dans sa version 3.1.1, permet de décrire notamment les opérations HTTP, paramètres, schémas et réponses. Un document de ce type facilite la lecture et les outils de contrôle. Il doit rester accompagné des règles métier que la structure des champs ne suffit pas à exprimer.
Donner un sens précis aux champs
Documentez chaque identifiant : qui le crée, s’il reste stable et dans quel périmètre il est unique. Une référence de commande du partenaire peut être unique dans son système sans l’être parmi tous les partenaires. Le serveur doit tenir compte de ce contexte.
Pour les montants, précisez l’unité, la devise et la représentation choisie. Pour les dates, distinguez une date civile d’un instant horodaté. Une échéance de facture et une heure de modification ne portent pas la même information.
| Champ fictif | Décision à documenter |
|---|---|
externalReference | Unicité par partenaire et conservation lors des relances |
currency | Valeurs acceptées et cohérence avec le montant |
requestedDate | Date civile sans conversion implicite de fuseau |
status | Valeurs possibles et transitions autorisées |
comment | Longueur, caractères admis et traitement d’une valeur vide |
Indiquez la différence entre un champ absent, une chaîne vide et une valeur nulle lorsque le contrat les distingue. Lors d’une modification partielle, l’absence peut signifier « conserver la valeur » et une valeur nulle « effacer », mais ce comportement doit être défini et testé.
Décrire les erreurs utiles au partenaire
Une erreur doit permettre de décider quoi faire ensuite. Donnez un code stable pour l’analyse automatique et un message compréhensible pour le diagnostic. Précisez les informations de champ qui peuvent être retournées sans exposer de données confidentielles.
Séparez les situations : demande invalide, droits insuffisants, conflit métier et indisponibilité temporaire. Documentez les codes HTTP choisis et un exemple de réponse pour chaque cas significatif. Un message « erreur inconnue » sans identifiant de suivi complique le rapprochement avec les journaux du fournisseur.
Expliquez aussi ce que signifie un délai d’attente dépassé. Le partenaire ne peut pas supposer que l’opération a échoué. Les règles de relance et de détection des répétitions sont détaillées dans notre guide sur les doublons d’intégration CRM et ERP.
Prévoir la consultation de volumes importants
Une liste de résultats doit préciser sa pagination et son ordre. Si les données évoluent pendant la consultation, déterminez le comportement attendu : photographie à un instant donné ou parcours d’une liste vivante. Les garanties influencent la manière dont le partenaire évite les omissions.
Documentez les filtres de dates avec leurs bornes inclusives ou exclusives. Expliquez comment les suppressions sont représentées si le partenaire doit répliquer les données. Un dossier qui disparaît simplement de la liste peut rester indéfiniment dans le système distant.
Précisez les limites de taille et de fréquence applicables, avec la manière de détecter leur dépassement. Les valeurs peuvent dépendre du service ; elles doivent être connues des deux équipes avant les essais en charge.
Encadrer les droits et les environnements
Attribuez des accès distincts aux partenaires et aux environnements. La documentation indique comment obtenir et renouveler les identifiants, sans contenir de secret réel. Le périmètre autorisé doit être contrôlé côté serveur pour chaque demande.
Préparez un environnement de test avec des données fictives stables. Donnez des cas qui produisent un succès, une erreur de validation et un refus d’accès. Le partenaire doit pouvoir vérifier son comportement sans provoquer de modification en production.
Organiser les changements du contrat
Choisissez une politique de version et de retrait des anciennes interfaces. Précisez comment les partenaires sont informés, combien de temps ils disposent pour adapter leur système et comment leur migration sera vérifiée.
Même l’ajout d’une valeur de statut mérite un examen : certains consommateurs traitent une liste fermée et peuvent échouer face à une valeur inconnue. Testez les changements avec les intégrations concernées au lieu de supposer qu’un ajout est toujours sans effet.
Conservez des exemples de requêtes et de réponses dans les tests du projet. À chaque livraison, vérifiez leur conformité au contrat publié. Ajoutez enfin le contact technique et la procédure de signalement d’incident au dossier de maintenance, avec la version du contrat utilisée par chaque partenaire.