Une API définit la manière dont un logiciel demande des données ou une action à un autre. Elle permet à un site de créer un prospect dans un CRM, à un service de paiement de transmettre son résultat ou à une application mobile de consulter un compte. Une bonne API ne se résume pas à une liste d'adresses : elle fixe un contrat sur les données, les droits, les erreurs et les changements.
Partir des actions réelles
Identifiez les événements métier et les enregistrements nécessaires à l'intégration. Nommez clairement les opérations et ne renvoyez que les informations utiles. Décrivez les entrées acceptées, les réponses possibles et les erreurs. La documentation et ses exemples doivent refléter le service déployé, pas seulement une ancienne spécification idéale.
Intégrer la sécurité au contrat
Authentifiez chaque appelant et vérifiez ses droits sur l'enregistrement concerné, pas uniquement son rôle général. Limitez la fréquence des requêtes et validez toutes les données reçues. Les jetons secrets restent sur des serveurs de confiance. Journalisez les opérations touchant aux paiements, aux permissions ou aux données clients.
Prévoir les réseaux imparfaits
Une requête peut expirer alors que l'autre service a déjà terminé son travail. Rendez les écritures importantes idempotentes : une nouvelle tentative ne doit créer ni commande ni débit en double. Définissez des délais et des règles de reprise. Pour les événements, conservez les tentatives de livraison et prévoyez un moyen de rejouer les échecs.
Préparer les évolutions
Les clients et les services ne sont presque jamais mis à jour au même instant. Privilégiez les changements compatibles, versionnez les ruptures nécessaires et observez les clients qui utilisent encore l'ancien comportement. Une API bien entretenue permet au produit d'évoluer sans multiplier les correctifs fragiles dans chaque intégration.
