Comprendre les API : comment un site communique avec des services externes

Derrière un site moderne se cache rarement un système isolé. Une carte qui s'affiche, un paiement qui se valide, un avis client qui remonte, une météo qui s'actualise : à chaque fois, le site dialogue avec un service extérieur. Ce dialogue passe par des API. Comprendre ce qu'est une API et comment elle fonctionne éclaire une grande partie de l'architecture d'un site actuel.

Une API, c'est un contrat d'échange

API signifie Application Programming Interface, littéralement « interface de programmation ». C'est un point d'entrée standardisé que les développeurs utilisent pour faire communiquer deux applications sans connaître leur fonctionnement interne. L'image la plus juste est celle du serveur de restaurant : vous ne connaissez pas la cuisine, vous passez commande via un menu (l'API), et le plat vous revient. L'API définit ce que l'on peut demander et sous quelle forme la réponse arrive.

Ce découplage est essentiel : le service de paiement, de cartographie ou de messagerie peut évoluer en interne sans casser les sites qui l'utilisent, tant que le « contrat » de l'API reste stable.

Le modèle requête / réponse

La communication avec une API web repose sur le protocole HTTP, le même que celui des pages web. Le principe est simple : le site envoie une requête, l'API renvoie une réponse. La requête précise généralement :

Sur ce point, cette vidéo apporte un éclairage concret :

• une URL qui identifie la ressource visée (par exemple une liste de produits, un utilisateur) ;
• une méthode qui indique l'intention : GET pour lire, POST pour créer, PUT ou PATCH pour modifier, DELETE pour supprimer ;
• parfois des données et des informations d'authentification.

La réponse contient les données demandées et un code de statut HTTP qui résume le résultat : 200 pour un succès, 404 quand la ressource n'existe pas, 401 ou 403 pour un problème d'autorisation, 500 en cas d'erreur du serveur distant. Ces codes sont un langage commun à toutes les API web.

REST, GraphQL : les grands styles

La plupart des API web suivent le style REST, qui organise les échanges autour de ressources identifiées par des URL et manipulées avec les méthodes HTTP. Les données transitent le plus souvent au format JSON, un format texte léger, lisible et compris par tous les langages de programmation.

Une alternative de plus en plus répandue est GraphQL, un langage de requête où le client demande précisément les champs dont il a besoin, en un seul appel. Là où REST expose des points d'accès figés, GraphQL laisse au client le soin de composer sa demande, ce qui limite les données inutiles échangées. Chaque approche a ses usages ; aucune n'est universellement supérieure.

S'identifier : les clés et les jetons

Une API ne s'ouvre pas à n'importe qui. L'accès est contrôlé, généralement par :

• une clé d'API : un identifiant secret transmis à chaque requête, qui identifie l'application appelante ;
• un jeton (souvent via le protocole OAuth) : un accès temporaire et délimité, utilisé notamment quand un service agit au nom d'un utilisateur.

Ces secrets doivent rester confidentiels et ne jamais être exposés côté navigateur en clair, sous peine d'être détournés. Ils passent normalement par le serveur du site, qui joue l'intermédiaire avec l'API externe.

Les webhooks : quand c'est le service qui appelle

Le modèle requête/réponse suppose que le site interroge l'API. Mais parfois, c'est l'inverse qui est utile : le service externe doit prévenir le site qu'un événement s'est produit (un paiement confirmé, un colis expédié). C'est le rôle des webhooks : le site expose une URL que le service appelle automatiquement quand l'événement survient. On passe d'une logique où l'on demande sans cesse « y a-t-il du nouveau ? » à une logique où l'on est notifié en temps réel.

Ce qui distingue une intégration robuste

Brancher une API n'est pas seulement « faire fonctionner l'appel ». Une intégration solide anticipe ce qui peut mal tourner :

• Gérer les erreurs : un service externe peut être lent, indisponible ou renvoyer une erreur. Le site doit le prévoir plutôt que de planter.
• Respecter les limites de débit (rate limits) : la plupart des API plafonnent le nombre d'appels autorisés sur une période. Les dépasser fait échouer les requêtes.
• Mettre en cache les réponses qui changent peu, pour éviter des appels répétés inutiles et gagner en rapidité.
• Vérifier l'authenticité des webhooks reçus, souvent via une signature, pour ne pas traiter une notification falsifiée.

Intégrer une API : côté front-end ou côté back-end ?

C'est la question qui décide de la suite d'une intégration : qui appelle l'API ? Le navigateur du visiteur (côté front-end) ou le serveur du site (côté back-end) ? Les deux fonctionnent, mais elles n'engagent pas les mêmes contraintes.

L'appel côté front-end part directement du navigateur, en JavaScript. C'est le plus rapide à mettre en place, et c'est ce qu'on trouve dans la plupart des widgets embarqués. Trois limites s'imposent alors :

• Le secret est exposé. Tout ce qui part du navigateur est lisible par le visiteur : une clé d'API placée dans le code front est publique, quelles que soient les précautions d'obfuscation.
• Le CORS s'applique. Le navigateur bloque par défaut les requêtes vers un autre domaine ; l'API distante doit explicitement autoriser l'origine du site via ses en-têtes Access-Control-Allow-*, faute de quoi l'appel échoue côté client.
• Le contenu n'existe pas à la première réponse HTML. Les données arrivent après l'exécution du script : elles ne sont pas dans le document servi, ce qui compte pour l'indexation et pour l'affichage sur un appareil lent.

L'appel côté back-end passe par le serveur du site, qui interroge l'API puis renvoie le résultat déjà mis en forme. C'est la voie retenue dès qu'il y a un secret à protéger, des données personnelles en jeu ou un besoin de cache :

• la clé ou le jeton reste sur le serveur, jamais transmis au navigateur ;
• le serveur peut mettre en cache la réponse et absorber les limites de débit de l'API, au lieu de multiplier les appels autant que de visiteurs ;
• le HTML servi contient déjà les données, donc pas de dépendance à l'exécution d'un script chez le visiteur ;
• en cas de panne du service distant, le serveur peut servir la dernière valeur connue plutôt qu'une zone vide.

Le schéma le plus courant combine les deux : le serveur joue le rôle de proxy, il expose au front une adresse interne du site, et c'est lui qui détient la clé et parle à l'API externe. Le front-end garde son interactivité, le secret ne sort jamais, et le cache devient possible.

Le seul cas où l'appel direct depuis le navigateur se défend sans réserve : une API publique, sans clé secrète, dont les données n'ont pas besoin d'être indexées — une carte interactive, un flux d'actualité secondaire, un widget de disponibilité.

Questions fréquentes sur les API et les web services

API ou web service : est-ce la même chose ?

Les deux termes se recouvrent largement et sont souvent employés l'un pour l'autre. « Web service » désigne historiquement un service exposé sur le réseau via des protocoles standardisés — la génération SOAP en est l'exemple typique. « API » est le terme plus large : c'est l'interface de programmation, qu'elle passe par le web ou non. En pratique, aujourd'hui, quand on parle d'un web service on parle presque toujours d'une API web de style REST échangeant du JSON en HTTP.

Faut-il forcément une API pour intégrer des données externes ?

Non, mais c'est la voie la plus solide. Un fichier déposé régulièrement (CSV, XML) ou un export planifié reste une intégration valable quand les données changent peu et qu'aucune action temps réel n'en dépend. L'API devient nécessaire dès qu'il faut une donnée à jour au moment de l'affichage, une écriture en retour, ou un événement remonté à la seconde — auquel cas le webhook complète l'API.

Qu'appelle-t-on le « contrat » d'une API ?

C'est la description de ce que l'API accepte et de ce qu'elle renvoie : les adresses disponibles, les paramètres attendus, la forme exacte de la réponse, les codes d'erreur possibles. Ce contrat est le plus souvent publié dans une documentation et, pour les API REST, formalisé dans un schéma lisible par machine (OpenAPI). Tant qu'il ne change pas, le fournisseur peut réécrire tout son code interne sans casser les sites qui l'appellent : c'est précisément l'intérêt du découplage.

Ce qui compte vraiment

Une API est le langage par lequel les logiciels se parlent. Grâce à ce mécanisme de requêtes et de réponses standardisées, un site peut s'appuyer sur des services spécialisés — paiement, cartographie, messagerie, données — sans les réinventer. La valeur technique se joue moins dans le fait d'appeler une API que dans la manière de le faire : sécuriser les accès, gérer les erreurs et les limites, et concevoir l'intégration pour qu'elle reste fiable même quand le service distant, lui, ne l'est pas.