API :
comment relier
les systèmes

Qu’est-ce qu’une API, simplement ?

Une API est une interface de programmation : un ensemble de règles qui permet à un composant logiciel de s’adresser à un autre. Ces règles précisent les actions disponibles, les données à transmettre et la réponse attendue. API signifie Application Programming Interface. Une personne appuie sur un bouton dans une application, et le logiciel peut appeler une API pour exécuter l’action demandée.

Imaginez un site qui reçoit des demandes de fourniture d’équipements. Un visiteur remplit un formulaire. Le serveur du site vérifie les données et demande au CRM de créer une demande avec ces champs. Le CRM renvoie un identifiant de fiche ou un message d’erreur. Le commercial n’a plus à recopier chaque demande à la main. Mais cet échange ne fonctionne qu’après configuration : la présence d’une API dans le CRM ne signifie pas que le site y est déjà relié.

Les bibliothèques, les systèmes d’exploitation, les navigateurs et les services externes peuvent tous proposer des API. Tous les appels API ne passent pas par Internet. Un navigateur fournit par exemple des interfaces pour manipuler les éléments d’une page. Cet article porte surtout sur les API web qui relient un site, un CRM, un système de gestion et d’autres services. La distinction entre les interfaces du navigateur et celles de services tiers est expliquée dans l’introduction de MDN.

Comment fonctionne une requête API

Un échange HTTP classique met en jeu un client, le programme qui demande des données ou une action, et un serveur qui reçoit la requête. Le client peut ici être le serveur de votre site, et non le navigateur du visiteur. Un même système peut jouer l’un ou l’autre rôle selon la situation.

Une requête comporte généralement une adresse, une méthode, des en-têtes et, si nécessaire, un corps contenant des données. L’adresse d’une opération précise s’appelle un point de terminaison, ou endpoint. La méthode aide à définir l’action. Les en-têtes peuvent indiquer le format et les informations d’accès. Le corps contient l’objet transmis, par exemple les champs d’une demande. La documentation de chaque API définit les éléments obligatoires.

L’adresse example.com est ici un exemple fictif : ce schéma sert à expliquer le principe, pas à connecter votre CRM. Même une opération équivalente peut utiliser des champs et des règles différents selon les services.

Consulter une véritable réponse API sans programmer

Pour commencer, vous pouvez consulter les informations publiques d’un dépôt de démonstration GitHub. Cet exemple ne crée ni ne modifie rien. Lors de la préparation de l’article, la requête a reçu une réponse réussie. Le service limite la fréquence des appels ; le résultat d’une nouvelle requête dépend donc aussi des conditions d’accès du moment.

1. Ouvrez l’adresse publique de l’exemple dans votre navigateur.
2. Repérez le champ full_name : il indique le propriétaire et le nom du dépôt.
3. Consultez private : la valeur booléenne false signifie que le dépôt n’est pas privé.
4. Comparez l’adresse API avec html_url : ce dernier renvoie vers la page habituelle destinée aux utilisateurs.

{
  "name": "Hello-World",
  "full_name": "octocat/Hello-World",
  "private": false,
  "html_url": "https://github.com/octocat/Hello-World"
}

Il s’agit d’un extrait abrégé de la réponse, pas du document complet. Les accolades, noms de champs et valeurs constituent une représentation JSON. Le programme lit des champs précis et n’a pas besoin de la mise en page. L’ordre des champs ne doit pas être interprété comme porteur de sens.

Afficher le code d’état dans Postman

Dans l’interface anglaise de Postman, ouvrez un nouvel onglet de requête HTTP avec Add, choisissez GET, collez la même URL et cliquez sur Send. Vérifiez le statut et le corps de la réponse dans le panneau inférieur. N’ajoutez aucun secret de votre entreprise pour cet exemple public. Les boutons et l’emplacement des panneaux varient selon la version de l’application.

Pour aller plus loin avec GitHub, consultez le guide officiel de l’API REST : il décrit les méthodes, les paramètres, les en-têtes et les accès. Notre exemple se limite à lire un objet public. Il ne confirme pas que l’intégration avec votre CRM ou votre système de paiement est configurée.

REST, JSON, webhook et SDK : que peut-on comparer ?

Ces termes décrivent différentes parties d’une solution. JSON est un format de données. REST est un style architectural. Un webhook sert à notifier un autre système d’un événement. Un SDK est un ensemble d’outils de développement qui peut faciliter l’utilisation d’une API. Ce ne sont pas des options mutuellement exclusives.

Une API web peut utiliser HTTP et JSON sans respecter pleinement les principes REST. Il existe aussi SOAP, les appels de procédures distantes et d’autres approches. Pour le commanditaire, la disponibilité des opérations nécessaires, de la documentation et de l’assistance compte davantage qu’un nom de technologie à la mode. Vous trouverez un aperçu dans le guide AWS sur les API.

Interrogation périodique et notification d’événement

Avec l’interrogation périodique, l’intégration demande régulièrement ce qui a changé depuis la dernière vérification. Avec un webhook, la source envoie elle-même une notification à l’adresse convenue, par exemple pour signaler la modification d’une commande. Cela réduit l’attente et les requêtes sans résultat, sans supprimer la gestion des erreurs.

Les webhooks peuvent arriver plusieurs fois ou dans un ordre inattendu. Les règles de nouvelle livraison varient selon les fournisseurs. Il faut authentifier les notifications, reconnaître les événements déjà traités et retrouver les changements manqués. GitHub recommande par exemple HTTPS, un secret de webhook et le suivi des identifiants de livraison ; les détails figurent dans sa documentation. Ne transposez pas automatiquement les délais de réponse d’un service à un autre.

À quoi servent les API pour un site et une entreprise

Partez d’une tâche manuelle précise ou d’une perte de données. « Connecter tous les systèmes » ne définit pas le résultat du projet. Une exigence utile serait : chaque demande confirmée du site apparaît dans le bon pipeline CRM, avec sa source et un responsable ; les demandes non transmises sont visibles dans un journal.

Il s’agit de cas d’usage, pas d’une garantie que le service choisi prend en charge tous les champs. Certains produits ne proposent l’API que dans certaines offres ou n’exposent qu’une partie des fonctions de leur interface. L’étude préalable fait partie des prestations de mise en place de CRM, développement de sites web et développement d’agents d’IA.

Que vérifier dans la documentation et le cahier des charges

Demandez au développeur de présenter la documentation de l’opération requise et un petit scénario de vérification. Un document qui indique simplement « intégration par API » laisse trop de place à l’interprétation. Précisez notamment :

• Systèmes et objets. Quel CRM et quelle version du site sont concernés, et ce qui constitue une demande, une commande ou un client.
• Sens de circulation. Uniquement site → CRM, ou aussi des mises à jour de statut dans l’autre sens. Les échanges bidirectionnels nécessitent des règles de résolution des conflits.
• Source de référence. Où les prix sont modifiés et quel système fait foi en cas de divergence.
• Champs et référentiels. Correspondance des noms, champs obligatoires, types, valeurs autorisées, devise et fuseau horaire.
• Moment de l’échange. Immédiatement après l’événement, selon un planning ou manuellement ; délai acceptable.
• Volumes. Charge habituelle, pics de flux et export initial des fiches accumulées.
• Erreurs. Ce qui est réessayé automatiquement, ce qui est transmis au responsable et comment la file d’attente est rétablie.
• Exploitation. Qui détient les accès et assure la documentation et l’assistance après le lancement.

Pour les listes, vérifiez la pagination, c’est-à-dire le découpage des résultats en pages. Récupérer correctement les 100 premières fiches ne signifie pas avoir exporté les 8 000. La synchronisation des changements nécessite des points de reprise et un moyen clair de rejouer un intervalle manqué. Les paramètres précis proviennent de la documentation du fournisseur.

Comprendre les erreurs d’API

Un code HTTP décrit le résultat d’une requête au niveau du protocole. Le message dans le corps de la réponse et le journal de l’intégration aident à en comprendre la cause. Aucun code ne prouve à lui seul que le processus métier s’est achevé correctement. Les principales valeurs sont expliquées dans la référence HTTP de MDN.

Pour contacter le support, conservez l’heure et son fuseau horaire, l’opération, l’identifiant de requête, le code, un exemple anonymisé et le résultat attendu. Ne joignez pas de secret d’accès actif. Dire « cela ne fonctionne pas parfois » sans ces éléments allonge le diagnostic.

Un cas particulier survient lorsque le navigateur bloque la lecture de la réponse à cause de CORS. Il s’agit d’une restriction d’accès entre origines, pas de la preuve que l’API est indisponible pour tous les clients. Un développeur doit vérifier le mode de connexion. Désactiver la protection du navigateur des visiteurs ne corrige pas l’intégration.

Pourquoi une requête réussie ne suffit pas

Prenons un exemple pédagogique : le CRM a créé une demande, mais la réponse s’est perdue en chemin. Le site constate un dépassement du délai et renvoie la même demande. Si l’intégration ne reconnaît pas la répétition, le commercial obtient deux fiches. Un dépassement de délai signifie que le client n’a pas reçu de réponse à temps ; il ne garantit pas l’annulation de l’action sur le serveur.

Pour ces situations, prévoyez une protection contre les doublons : identifiant externe stable, clé d’idempotence prise en charge par le service ou autre mécanisme convenu. L’idempotence signifie que répéter la même opération ne produit aucun effet supplémentaire par rapport à sa première exécution. Ajouter arbitrairement un en-tête portant ce nom ne rend pas une API tierce idempotente.

• Les nouvelles tentatives sont limitées. Des pauses, un nombre maximal de tentatives et un traitement distinct des erreurs irrécupérables sont prévus.
• La file d’attente est persistante. Après le redémarrage du processus, les événements non transmis restent visibles et peuvent être traités.
• L’ordre est pris en compte. Un ancien statut ne doit pas écraser un état confirmé plus récent.
• Un rapprochement est prévu. Une comparaison de contrôle des enregistrements révèle les pertes absentes du journal d’erreurs habituel.
• Un responsable est désigné. L’alerte de panne parvient à une personne qui connaît la procédure de reprise.

Testez la fiabilité avec des scénarios contrôlés dans un environnement de test. Il n’est pas nécessaire de provoquer des erreurs massives sur le site en production pour une démonstration. Pour un export volumineux, vérifiez séparément la reprise après interruption et l’absence de retraitement de la partie déjà terminée.

Gérer les clés et les droits d’accès

Une clé secrète ou un jeton donne accès au service ; ce n’est pas un réglage décoratif. Ses droits doivent correspondre à l’opération : lire un catalogue ne nécessite pas forcément de pouvoir supprimer des commandes. Séparez les environnements de production et de test, et documentez le propriétaire du compte ainsi que la procédure de remplacement des accès.

Ne placez pas de secrets serveur dans du JavaScript, du HTML, des captures d’écran ou des dépôts publics. Certains services fournissent volontairement des clés publiques pour navigateur ; utilisez-les uniquement selon les règles du fournisseur et avec les restrictions prévues. Une clé n’est pas publiable sans risque simplement parce que le site en a besoin.

Un jeton valide ne remplace pas le contrôle des droits sur un objet précis. Un utilisateur autorisé à consulter sa commande ne doit pas pouvoir accéder à celle d’un autre en changeant l’identifiant. Les défaillances de ce contrôle figurent dans la liste des risques OWASP API Security. Lors de la recette, demandez des tests des scénarios autorisés comme interdits avec des comptes de test.

Les identifiants et la description des pannes sont utiles dans les journaux ; les coordonnées complètes des clients et les secrets sont souvent inutiles. Convenez des données transmises, des accès aux journaux et de leur durée de conservation. Pour une intégration d’IA, définissez séparément quelles informations peuvent être envoyées au fournisseur choisi.

Valider l’intégration livrée par le développeur

Demandez une démonstration du parcours complet d’un objet de test. Pour une demande, cela comprend le formulaire, l’enregistrement sur le site, le transfert, la fiche CRM et l’attribution à un responsable. Vérifiez les valeurs dans le système destinataire. Une notification du navigateur et un statut HTTP 200 ne remplacent pas cette vérification.

Consignez dans le procès-verbal de test les identifiants précis des objets testés, la date, le résultat et les réserves restantes. Convenez à l’avance des exigences chiffrées du projet : délai acceptable, volume et temps de reprise. Il n’existe pas de règle universelle imposant que « l’API réponde en une seconde » pour toutes les opérations.

Après la démonstration, récupérez la description des échanges, les instructions de démarrage et de reprise, l’accès aux journaux et la procédure de support. Le processus général de transfert du projet est détaillé dans le guide de recette d’un site web. Pour relier le site au CRM, consultez également le plan de déploiement CRM.

Points à formaliser avant le lancement

Questions fréquentes sur les API