API, JSON et coopération entre systèmes distincts

Ce qu’est une API

Une API (interface de programmation d’application) est la façon définie dont un élément logiciel demande à un autre de faire quelque chose. Elle indique ce qu’on peut demander, ce qu’il faut fournir, ce qu’on reçoit en retour et ce qui peut mal se passer. Le mot qui compte est définie : une API est un contrat. Le fournisseur promet de la maintenir en état de marche ; le consommateur promet de n’utiliser que ce qu’elle décrit.

Le restaurant est l’analogie habituelle. La carte indique ce que vous pouvez commander et ce que contient chaque plat ; le serveur porte votre commande en cuisine et vous rapporte le résultat. Vous n’entrez pas dans la cuisine, et vous n’avez pas besoin de savoir si le chef cuisine au gaz ou à l’induction. La cuisine peut changer d’équipement, de personnel et de fournisseurs à volonté, tant que les plats de la carte arrivent toujours comme décrit. La carte est l’API, la cuisine est l’implémentation, et c’est la séparation entre les deux qui permet à chaque côté de changer indépendamment de l’autre.

C’est la même idée que les interfaces vues dans organiser le code, appliquée à toutes les échelles. C’est aussi pourquoi les architectes accordent tant d’importance aux API : une API est l’endroit où le travail d’une équipe rencontre celui d’une autre, et dès que d’autres en dépendent, elle coûte cher à modifier.

API internes au processus et API web

Certaines API sont appelées à l’intérieur d’un même programme en cours d’exécution. Quand du code Python appelle json.loads(text), il utilise l’API du module json de la bibliothèque standard : un appel de fonction qui prend quelques nanosecondes et n’échoue que si l’entrée est incorrecte. Les fonctions et classes publiques d’une bibliothèque forment son API interne au processus.

Une API web est appelée par un réseau, en général avec HTTP (voir comment les ordinateurs communiquent). L’appelant et le fournisseur peuvent se trouver sur des machines différentes, être écrits dans des langages différents et appartenir à des organisations différentes. Une application bancaire mobile parle à l’API web de la banque ; les serveurs de la banque parlent à l’API d’un réseau de cartes ; une boutique parle à l’API d’un prestataire de paiement.

La différence n’est pas superficielle. Un appel réseau est des milliers à des millions de fois plus lent qu’un appel de fonction, et il peut échouer d’une façon dont un appel de fonction ne le peut pas : le réseau perd la requête, le serveur est surchargé, la réponse arrive après que l’appelant a abandonné, ou la requête a réussi mais la réponse s’est perdue, si bien que l’appelant ne peut pas savoir si le paiement est passé. Une grande partie de la conception des systèmes distribués, traitée au chapitre 6, consiste à vivre avec ces défaillances.

REST : ressources, URL et verbes

La plupart des API web suivent aujourd’hui le style appelé REST (Representational State Transfer), décrit par Roy Fielding dans sa thèse de doctorat de 2000. Fielding a défini REST comme un ensemble de contraintes pour les grands systèmes en réseau comme le web ; dans l’usage courant, « une API REST » désigne quelque chose de plus simple : une API HTTP organisée autour de ressources.

Une ressource est une chose que l’API expose : un client, une commande, une prévision. Chacune a une URL, comme /orders/1042. Une collection de ressources a aussi une URL, comme /orders. Le client agit sur les ressources avec les méthodes HTTP standard, lit le code d’état du résultat et échange des données dans le corps, en général au format JSON. Les mêmes quelques verbes fonctionnent donc pour toutes les ressources, ce qui rend prévisibles les API REST bien conçues.

Les codes d’état portent un sens sur lequel un programme client peut agir. Un code 4xx indique que le client a fait quelque chose de travers : 400 pour une requête mal formée, 401 quand les identifiants manquent ou ne sont pas valides, 403 quand l’appelant est connu mais n’a pas l’autorisation, 404 quand la ressource n’existe pas, 429 quand il a envoyé trop de requêtes. Un code 5xx indique que le serveur a échoué : 500 pour une erreur inattendue, 503 quand il est temporairement indisponible. La distinction compte, car renvoyer telle quelle une requête qui a reçu un 4xx échouera de nouveau, alors que renvoyer une requête qui a reçu un 503 un peu plus tard peut réussir.

Les données circulent au format JSON (JavaScript Object Notation), un format texte normalisé par la RFC 8259. Il n’a que quelques éléments de base : des objets (des paires nom-valeur entre accolades), des tableaux (des listes entre crochets), des chaînes entre guillemets doubles, des nombres, true, false et null. Malgré son nom, tous les langages courants savent le lire et l’écrire, et c’est pourquoi il est devenu la langue commune des API web. D’autres styles existent et répondent à d’autres besoins : GraphQL permet au client de préciser exactement les champs qu’il veut, et gRPC utilise un format binaire compact pour des appels rapides entre services ; le chapitre 6 les compare.

GET /v1/forecast?city=Kigali&days=2 HTTP/1.1
Host: api.example.com
Authorization: Bearer sk_test_4f9a...
Accept: application/json

HTTP/1.1 200 OK
Content-Type: application/json

{
  "city": "Kigali",
  "units": "metric",
  "days": [
    {"date": "2026-10-23", "min_c": 16, "max_c": 27, "rain_chance": 0.6},
    {"date": "2026-10-24", "min_c": 16, "max_c": 26, "rain_chance": 0.4}
  ]
}

import os
import requests

API_KEY = os.environ["WEATHER_API_KEY"]   # never hard-code secrets

resp = requests.get(
    "https://api.example.com/v1/forecast",
    params={"city": "Kigali", "days": 2},
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=3,                 # give up after 3 seconds
)
resp.raise_for_status()        # raises an error for 4xx and 5xx
tomorrow = resp.json()["days"][0]
print(tomorrow["max_c"], "degrees, rain chance", tomorrow["rain_chance"])

Qui appelle ? Clés d’API et jetons

La plupart des API ont besoin de savoir qui appelle, pour facturer, limiter et décider de ce que l’appelant peut voir. Deux idées méritent d’être distinguées dès le départ. L’authentification répond à la question « qui êtes-vous ? » ; l’autorisation répond à « qu’avez-vous le droit de faire ? »

Une clé d’API est une longue chaîne secrète qui identifie l’application appelante ; elle est envoyée avec chaque requête, en général dans un en-tête. C’est simple, et cela identifie un programme plutôt qu’une personne. Un jeton d’accès (access token) est un identifiant de courte durée délivré après la connexion d’une personne, souvent au nom d’un utilisateur précis et avec des droits précis (« lire l’agenda de cet utilisateur, mais pas ses e-mails ») ; il est en général envoyé sous la forme Authorization: Bearer <token>. Les jetons expirent, si bien qu’un jeton volé n’est utilisable que pendant un temps limité. Les protocoles standard qui les sous-tendent, OAuth 2.0 et OpenID Connect, sont traités dans identité et accès.

Quel que soit le moyen utilisé, les règles sont les mêmes : n’envoyer les identifiants que par HTTPS, les garder hors du code source et hors des applications mobiles, d’où n’importe qui peut les extraire, les stocker dans un gestionnaire de secrets ou dans les paramètres d’environnement, et pouvoir les révoquer et les remplacer rapidement.

Webhooks : l’API vous rappelle

Parfois, le client a besoin de savoir quand quelque chose se produit du côté du fournisseur : un paiement réussit, un colis est livré, un document est signé. Le client pourrait faire du polling, c’est-à-dire demander « est-ce que c’est fait ? » toutes les quelques secondes, ce qui gaspille des requêtes et repère quand même l’événement en retard. Un webhook inverse le sens : le client enregistre une URL qui lui appartient, et le fournisseur envoie un POST HTTP à cette URL quand l’événement se produit. Le terme a été inventé par Jeff Lindsay en 2007.

Les webhooks apportent des responsabilités. L’endpoint destinataire est sur l’internet public, il doit donc vérifier que chaque appel vient bien du fournisseur, en général en vérifiant une signature cryptographique placée dans un en-tête. Les fournisseurs réessaient quand le destinataire ne répond pas, si bien qu’un même événement peut arriver deux fois et que le destinataire doit reconnaître les doublons (traiter un doublon ne doit pas expédier la commande deux fois). Et les événements peuvent arriver dans le désordre.

Attendre une réponse, ou non : synchrone et asynchrone

Jusqu’ici, tout était synchrone : l’appelant envoie une requête et attend la réponse avant de continuer, comme lors d’un appel téléphonique. C’est simple à comprendre, et c’est le bon choix quand l’appelant a vraiment besoin de la réponse tout de suite, par exemple « ce paiement par carte a-t-il été accepté ? ». Sa faiblesse est que l’appelant n’est jamais plus disponible ni plus rapide que tout ce qu’il attend.

L’autre possibilité est la messagerie asynchrone, qui ressemble plutôt à une lettre déposée dans une boîte aux lettres. L’émetteur place un message dans une file de messages et poursuit son travail. Le destinataire prend les messages dans la file quand il est prêt. Si le destinataire est lent ou en panne pendant une heure, les messages attendent au lieu d’échouer. Quand la boutique confirme une commande, l’envoi de l’e-mail de confirmation n’a pas besoin de bloquer l’écran du client ; un message OrderPlaced peut aller dans une file, et le service d’e-mails le traitera un instant plus tard.

L’asynchronisme n’est pas gratuit. L’émetteur n’apprend pas tout de suite si le travail a réussi, le système devient plus difficile à tracer et à tester, et les messages peuvent être livrés plus d’une fois. Décider quelles interactions doivent être synchrones et lesquelles asynchrones est l’une des décisions centrales des systèmes distribués, traitée en détail dans communication et API et dans files et contre-pression.

Vivre avec les API des autres : SDK, versions et limites

Beaucoup de fournisseurs publient un SDK (kit de développement logiciel) : une bibliothèque pour chaque langage courant, qui enveloppe les appels HTTP dans des fonctions ordinaires, si bien qu’un développeur écrit client.refunds.create(payment_id) au lieu de construire les requêtes à la main. Les SDK font gagner du temps et gèrent des détails comme les nouvelles tentatives et les signatures, mais ils sont une dépendance de plus à tenir à jour.

Dès qu’une API a des utilisateurs, la modifier devient délicat. Ajouter un nouveau champ facultatif à une réponse est en général sans danger. Renommer un champ, en supprimer un, changer son type ou son sens, ou rendre obligatoire une entrée facultative est un changement cassant (breaking change) : chaque client qui comptait sur l’ancien comportement casse, souvent en production, et souvent chez un fournisseur qui ne peut ni voir ni mettre à jour ces clients (pensez aux applications mobiles que les utilisateurs ne mettent jamais à jour). Les fournisseurs versionnent donc leurs API, par exemple avec /v1/ et /v2/ dans l’URL ou avec un en-tête de version, maintiennent l’ancienne version pendant une durée annoncée et publient bien à l’avance des dépréciations (des avis indiquant qu’une fonctionnalité va être retirée). Une observation de Hyrum Wright, connue sous le nom de loi de Hyrum, ajoute une mise en garde : avec suffisamment d’utilisateurs, quelqu’un finira par dépendre de chaque comportement observable d’une API, y compris de ceux que la documentation n’a jamais promis.

Les fournisseurs se protègent aussi avec une limite de débit (rate limit) : un plafond comme 100 requêtes par minute et par clé. Les requêtes au-delà de la limite sont refusées avec le statut 429 Too Many Requests, souvent accompagné d’un en-tête Retry-After qui indique quand réessayer. Les clients doivent la respecter, étaler leurs requêtes, mettre en cache les réponses qui changent rarement et ralentir quand on le leur demande.

Utiliser des API tierces : développer ou acheter

Les applications modernes sont autant assemblées qu’écrites. Une application de livraison de repas peut utiliser l’API d’un prestataire de paiement pour encaisser les paiements par carte, une API de cartographie pour les adresses et les itinéraires, une API d’e-mail ou de SMS pour les reçus, et un service de notifications push pour « votre livreur est tout près ». Chacune fait gagner des mois de travail spécialisé et apporte une expertise (sécurité des cartes, données cartographiques mondiales, délivrabilité des e-mails) que peu d’équipes pourraient égaler.

Chacune apporte aussi une dépendance que l’équipe ne contrôle pas : les pannes du fournisseur deviennent vos pannes, ses changements de prix deviennent vos coûts, sa façon de traiter les données entre dans votre conformité, et le quitter peut obliger à réécrire du code. Les professionnels gèrent cela délibérément. Ils isolent chaque fournisseur derrière une petite interface qui leur est propre, pour qu’une seule partie du code connaisse l’API du fournisseur ; ils fixent des délais d’expiration et décident de ce qui se passe quand le fournisseur est en panne ; ils surveillent la page d’état et le journal des modifications du fournisseur ; et ils notent ce qu’il faudrait faire pour en changer.

Pourquoi c’est important pour l’architecture

L’architecture porte en grande partie sur les parties d’un système et les contrats entre elles, et les API sont ces contrats rendus concrets. Une API facile à bien utiliser et difficile à casser permet aux équipes de travailler en parallèle et de modifier librement leur fonctionnement interne ; une API qui fuit ou qui est instable couple tout le monde à tout le monde. Le choix entre appels synchrones et messages asynchrones détermine la façon dont les défaillances se propagent. Le chapitre 3 explique les principes des bonnes interfaces (masquage de l’information et abstraction), et le chapitre 6 montre comment les choix d’API et de messagerie font ou défont les systèmes distribués.