S'accorder sur le sens des données
Définissez les identifiants, les unités, les formats, les valeurs autorisées et les règles de calcul. Un champ nommé montant peut représenter un total hors taxes dans un système et toutes taxes comprises dans un autre. Le contrat d'interface doit également préciser quelle application fait autorité pour chaque information.
Documentez les états successifs de l'objet échangé. Un dossier transmis, reçu, contrôlé et validé n'est pas dans le même état. Les accusés techniques et les confirmations métier doivent être distingués pour éviter de déclarer terminé un traitement encore en attente.
Prévoir les erreurs et les répétitions
Que se passe-t-il après une coupure ? Une requête rejouée crée-t-elle un doublon ? Comment rapproche-t-on les opérations dont le résultat est incertain ? Des identifiants de corrélation, des règles d'idempotence et une file d'anomalies peuvent être nécessaires selon le service, mais leur mise en place doit être vérifiée.
Organiser l'exploitation commune
Précisez les limites de volume, la durée de support des versions, les habilitations, la supervision et l'interlocuteur en cas d'échec. Testez avec des exemples complets et des cas d'erreur. Le livrable utile n'est pas seulement une documentation d'API : c'est un échange compris, surveillé et réparable.