Une API est simplement la façon dont un logiciel demande quelque chose à un autre. Votre boutique en ligne demande à votre système d'inventaire combien d'unités il reste. Votre logiciel de comptabilité demande à la banque les transactions du jour. Un scanner d'entrepôt indique au système principal qu'une palette vient d'être expédiée.
Ces connexions commencent généralement de manière petite et pratique. Mais une fois que plusieurs systèmes en dépendent, elles deviennent partie intégrante du fonctionnement de l'entreprise. Les petits points flous, comme ce que signifie une erreur particulière ou s'il est sûr d'envoyer une requête deux fois, finissent par causer des problèmes partout. La fiabilité commence par clarifier ces points.
Décrire le travail en mots simples d'abord
Avant d'écrire le moindre code, je décris à quoi sert réellement la connexion. Que demande un système à l'autre ? Que doit-il être vrai avant que cela puisse arriver ? Comment savons-nous que c'est terminé ? Quelles sont les réponses « non » normales, comme « en rupture de stock », et qu'est-ce qui compte comme une faute réelle ?
Cela permet de garder la connexion concentrée sur la tâche commerciale plutôt que sur la façon dont la base de données est structurée aujourd'hui. Cela garantit également que tout le monde entend la même chose par le même mot. Si « terminé » signifie « expédié » à un endroit et « payé » à un autre, quelqu'un finira par faire une erreur coûteuse.
Rendre les messages d'erreur utiles
Lorsqu'une opération est rejetée, le message doit dire ce qui n'a pas fonctionné et quoi faire à ce sujet. « La date de livraison ne peut pas être dans le passé » est utile. « Quelque chose a mal tourné » ne l'est pas.
Différents problèmes méritent différentes réponses : informations manquantes, enregistrement inexistant, deux personnes modifiant la même chose en même temps, manque d'autorisation, ou une faute réelle du côté du système. Les messages d'erreur ne doivent pas non plus révéler des détails internes comme les mots de passe ou la structure de la base de données. Ceux-ci appartiennent aux journaux privés, où je peux tracer exactement ce qui s'est passé.
Prévoir la requête envoyée deux fois
Voici un problème courant. Un système envoie une commande, l'autre côté l'enregistre, mais la réponse est perdue en chemin. L'expéditeur ne sait pas si cela a fonctionné, donc il réessaie. Maintenant, il y a deux commandes.
La solution consiste à donner à chaque requête son propre numéro de référence, afin que le système récepteur puisse dire « J'ai déjà celle-ci » et renvoyer simplement le résultat original. Pour tout ce qui crée des commandes, des paiements ou des expéditions, je considère cela comme essentiel.
Certaines tâches prennent également du temps, comme la création d'un rapport volumineux ou le traitement d'un grand lot d'enregistrements. Dans ces cas-là, le système doit répondre immédiatement par « reçu, voici une référence pour vérifier », plutôt que de laisser l'expéditeur deviner si un long silence signifie succès ou échec.
Changer avec précaution
Une fois que d'autres systèmes dépendent d'une connexion, la modifier revient un peu à changer les règles d'un jeu en cours de route. Supprimer une information est évidemment risqué. Changer discrètement ce qu'une information signifie peut être tout aussi grave, et beaucoup plus difficile à repérer.
Lorsque des changements sont nécessaires, j'ajoute la nouvelle version à côté de l'ancienne si possible, je préviens tout le monde et donne un calendrier avant que quoi que ce soit ne soit retiré, et je vérifie qui utilise encore l'ancienne version avant de la désactiver.
S'en occuper une fois en ligne
Une connexion qui fonctionne sur l'ordinateur portable d'un développeur n'est pas terminée. En utilisation réelle, elle doit aussi :
- vérifier qui demande, et ce qu'il est autorisé à voir
- limiter la quantité que chaque appelant peut envoyer, afin qu'un système défectueux ne puisse pas le submerger
- garder les informations chiffrées pendant leur transfert
- être surveillée, afin que les ralentissements et les erreurs soient détectés tôt
- être accompagnée d'exemples clairs, afin que les personnes qui s'y connectent réussissent du premier coup
Le test d'une bonne connexion est simple : les systèmes qui l'utilisent peuvent compter sur elle, et les personnes qui s'en occupent peuvent comprendre ce qu'elle fait.
En bref
Une connexion fiable rend la bonne chose facile à faire et rend les problèmes faciles à comprendre. Des accords clairs, une gestion sûre des répétitions, des changements prudents et une bonne surveillance ne sont pas des extras ajoutés à la fin. Ils font partie de la construction correcte.