Qu'est-ce qu'une API ?

Une API (Application Programming Interface, ou interface de programmation applicative) est un ensemble de règles qui permet à deux logiciels de communiquer entre eux. Concrètement, elle définit comment un programme peut demander une information ou un service à un autre programme, et sous quelle forme la réponse sera renvoyée.

L'analogie du restaurant pour bien comprendre

Pour comprendre une API sans jargon technique, l'analogie du restaurant est la plus utilisée dans la vulgarisation informatique.

Dans un restaurant, le client ne va pas directement en cuisine préparer son plat. Il consulte un menu, passe sa commande auprès du serveur et le serveur transmet la demande à la cuisine. Une fois le plat prêt, le serveur le récupère puis le apporte au client.

Dans ce schéma :

• le client correspond à l'application qui a besoin d'une donnée ou d'un service (un site web, une application mobile, un script Python) ;
• la cuisine correspond au serveur qui détient la donnée ou exécute le traitement demandé ;
• le serveur du restaurant correspond à l'API elle-même : un intermédiaire qui transmet la demande dans un format compris par les deux parties, puis renvoie la réponse.

L'API ne montre jamais ce qui se passe « en cuisine ». Elle expose uniquement un menu de possibilités (les endpoints) et un format de commande précis à respecter.

Comment fonctionne une API ?

La requête et la réponse

Une API fonctionne selon le principe de requête et de réponse. Le client envoie une requête à un point d'accès précis, appelé endpoint et le serveur renvoie une réponse.

La requête contient généralement :

• une URL qui identifie la ressource demandée ;
• une méthode HTTP qui indique l'action souhaitée ;
• des paramètres ou un corps de requête qui contient les données envoyées ;
• des en-têtes (headers), qui transportent des informations complémentaires comme l'authentification.

Les méthodes HTTP courantes

La majorité des API web reposent sur le protocole HTTP et utilisent quatre principales méthodes :

• GET : récupérer une donnée sans la modifier (exemple : obtenir la météo actuelle) ;
• POST : envoyer une nouvelle donnée au serveur (exemple : créer un compte utilisateur) ;
• PUT : mettre à jour une donnée existante dans son intégralité ;
• DELETE : supprimer une ressource.

Les codes de statut HTTP

Chaque réponse d'API est accompagnée d'un code de statut qui indique si la requête a réussi ou échoué. Voici les codes les plus fréquents :

• 200 : la requête a réussi.
• 201 : une ressource a été créée avec succès.
• 400 : la requête est mal formée.
• 401 : l'authentification est requise ou invalide.
• 404 : la ressource demandée n'existe pas.
• 500 : une erreur est survenue côté serveur.

Le format JSON

La majorité des API modernes échangent des données au format JSON (JavaScript Object Notation). Ce format représente les informations sous forme de paires clé-valeur, lisibles à la fois par un humain et par une machine. Exemple d'une réponse JSON typique :

{
  "ville": "Cotonou",
  "temperature": 29,
  "unite": "celsius"
}

Les différents types d'API

Il y a plusieurs façons de classer les API : selon le style d'architecture (comment elles sont construites), selon la gestion d'état (stateless et stateful) et selon l'usage ou l'accès.

En se basant sur le style d'architecture, on distingue :

API REST

Une API REST (Representational State Transfer) organise les échanges autour de ressources identifiées par des URL et utilise les méthodes HTTP classiques (GET, POST, PUT, DELETE). C'est le style d'API le plus répandu sur le web aujourd'hui, notamment parce qu'il est simple à mettre en œuvre et à documenter.

API SOAP

Une API SOAP (Simple Object Access Protocol) repose sur un format d'échange strict basé sur XML. Elle est plus rigide que REST, mais reste utilisée dans certains secteurs qui exigent un haut niveau de sécurité et de validation, comme la banque ou les systèmes gouvernementaux.

API GraphQL

GraphQL est un langage de requête qui permet au client de demander exactement les champs dont il a besoin, en une seule requête. Contrairement à REST, où chaque endpoint renvoie une structure de données fixe, GraphQL laisse le client construire sa propre requête sur mesure.

Selon la gestion de l'état (stateless vs stateful), on distingue :

Enfin, selon les usages (ou le niveau d'accès), on distingue :

• les APIs publiques (ou open API) qui sont accessible à n'importe quel développeur, parfois avec inscription ;
• les APIs privées qui sont réservées à un usage interne, au sein d'une même entreprise ;
• les API partenaires qui sont partagées avec des entreprises externes sélectionnées, dans le cadre d'un accord commercial.

Pourquoi les API sont-elles importantes ?

Les API permettent à différents services de collaborer sans que les équipes de développement aient besoin de connaître le fonctionnement interne les unes des autres. Une application de livraison de repas peut ainsi :

• afficher une carte grâce à l'API d'un fournisseur de cartographie ;
• traiter un paiement grâce à l'API d'une plateforme bancaire ;
• envoyer une notification grâce à l'API d'un service de messagerie.

Ceci sans avoir à développer aucune de ces briques elle-même.

Cette logique de blocs interconnectés est aujourd'hui au cœur de la plupart des applications web et mobiles.

Exemple : interroger une API avec Python

Le langage Python est particulièrement adapté pour découvrir les API, grâce à la bibliothèque requests, simple à utiliser pour un débutant.

Installer la bibliothèque requests

pip install requests

Envoyer une requête GET

L'exemple suivant interroge une API publique gratuite qui renvoie des informations sur un utilisateur GitHub.

import requests

# Endpoint de l'API GitHub pour un utilisateur donné
url = "https://api.github.com/users/octocat"

# Envoi de la requête GET
reponse = requests.get(url)

# Vérification du code de statut
if reponse.status_code == 200:
    donnees = reponse.json()
    print("Nom d'utilisateur :", donnees["login"])
    print("Nombre de dépôts publics :", donnees["public_repos"])
else:
    print("Erreur lors de la requête :", reponse.status_code)

Ce script envoie une requête GET vers l'API GitHub, récupère la réponse au format JSON grâce à reponse.json(), puis affiche deux informations extraites de cette réponse.

Envoyer une requête avec des paramètres

Certaines API demandent des paramètres supplémentaires dans l'URL. La bibliothèque requests permet de les ajouter facilement avec l'argument params.

import requests

url = "https://api.agify.io"
parametres = {"name": "Aline"}

reponse = requests.get(url, params=parametres)

if reponse.status_code == 200:
    donnees = reponse.json()
    print(f"Âge estimé pour {donnees['name']} : {donnees['age']} ans")
else:
    print("Erreur :", reponse.status_code)

Envoyer une requête POST avec authentification

De nombreuses API exigent une clé d'API pour identifier l'application qui envoie la requête. Cette clé est généralement transmise dans les en-têtes de la requête.

import requests

url = "https://exemple-api.com/v1/messages"
cle_api = "votre_cle_api_ici"

en_tetes = {
    "Authorization": f"Bearer {cle_api}",
    "Content-Type": "application/json"
}

corps_requete = {
    "destinataire": "client@example.com",
    "message": "Bonjour, ceci est un test."
}

reponse = requests.post(url, json=corps_requete, headers=en_tetes)

if reponse.status_code == 201:
    print("Message envoyé avec succès.")
else:
    print("Échec de l'envoi :", reponse.status_code, reponse.text)

Une clé d'API ne doit jamais être écrite directement dans le code source d'un projet partagé ou publié en ligne. Elle doit être stockée dans une variable d'environnement ou un fichier de configuration exclu du dépôt de code.

La sécurité des API et le rôle des clés API

Qu'est-ce qu'une clé API ?

Une clé API est une chaîne de caractères unique qui identifie l'application ou l'utilisateur qui envoie une requête à une API. Elle fonctionne comme un mot de passe attribué automatiquement, sans intervention humaine à chaque connexion.

Quand une application envoie une requête accompagnée de sa clé API, le serveur peut :

• vérifier que l'application est bien autorisée à utiliser l'API ;
• suivre le nombre de requêtes effectuées, pour appliquer une limite d'usage (rate limiting) ;
• facturer l'utilisation si l'API est payante, en fonction du volume consommé ;
• bloquer l'accès en cas d'usage abusif ou suspect, en révoquant uniquement la clé concernée.

Comment une clé API est utilisée dans une requête ?

La clé API est généralement transmise de deux façons : dans les en-têtes HTTP (la méthode la plus sécurisée) ou directement dans l'URL sous forme de paramètre. Cette deuxième méthode est peu recommandée, car l'URL peut être enregistrée dans des journaux ou un historique de navigateur.

import requests

url = "https://exemple-api.com/v1/donnees"
cle_api = "votre_cle_api_ici"

# Méthode recommandée : la clé passe dans les en-têtes, pas dans l'URL
en_tetes = {
    "Authorization": f"Bearer {cle_api}"
}

reponse = requests.get(url, headers=en_tetes)

if reponse.status_code == 200:
    print(reponse.json())
elif reponse.status_code == 401:
    print("Clé API invalide ou manquante.")
else:
    print("Erreur :", reponse.status_code)

Pourquoi il ne faut jamais partager sa clé API ?

Une clé API doit être traitée avec le même niveau de confidentialité qu'un mot de passe. Une clé qui tombe entre de mauvaises mains permet à n'importe qui d'agir à la place du titulaire légitime, avec plusieurs conséquences :

• Usurpation d'usage : une personne malveillante peut envoyer des requêtes en se faisant passer pour l'application légitime, ce qui fausse les statistiques d'usage et peut déclencher un blocage du compte réel.
• Coûts financiers imprévus : si l'API est facturée à la requête, une clé volée peut générer une consommation massive et une facture inattendue pour le titulaire.
• Accès à des données sensibles : selon les droits associés à la clé, une personne malveillante peut lire, modifier ou supprimer des données appartenant au titulaire de la clé, y compris des données personnelles d'utilisateurs.
• Dépassement des limites d'usage : un usage abusif partagé entre plusieurs personnes épuise plus vite le quota de requêtes autorisé, ce qui peut bloquer l'application légitime.

Comment protéger une clé API ?

• Ne jamais l'écrire directement dans le code source, surtout si ce code est publié sur une plateforme comme GitHub, même sur un dépôt privé.
• Utiliser des variables d'environnement pour stocker la clé, en dehors du code versionné.
• Ajouter le fichier de configuration contenant la clé au fichier .gitignore, pour éviter qu'il soit envoyé par erreur sur un dépôt de code.
• Régénérer la clé immédiatement si elle a été exposée par erreur (par exemple publiée accidentellement en ligne), la plupart des fournisseurs d'API permettent de révoquer une ancienne clé et d'en générer une nouvelle.
• Limiter les droits associés à la clé au strict nécessaire, quand le fournisseur d'API le permet, pour réduire l'impact en cas de fuite.

Voici un exemple de récupération d'une clé API depuis une variable d'environnement, plutôt que directement dans le code :

import os
import requests

# La clé est lue depuis l'environnement, jamais écrite en dur dans le script
cle_api = os.environ.get("MA_CLE_API")

if cle_api is None:
    print("Clé API introuvable. Vérifiez la variable d'environnement.")
else:
    en_tetes = {"Authorization": f"Bearer {cle_api}"}
    reponse = requests.get("https://exemple-api.com/v1/donnees", headers=en_tetes)
    print(reponse.status_code)

Bonnes pratiques pour bien débuter avec les API

• Lire la documentation officielle de l'API avant de commencer : elle précise les endpoints disponibles, les paramètres attendus et les limites d'utilisation.
• Vérifier les limites de requêtes (rate limiting) : la plupart des API publiques limitent le nombre d'appels autorisés par minute ou par jour.
• Gérer les erreurs systématiquement, en vérifiant le code de statut avant d'exploiter les données reçues.
• Protéger ses clés d'API en les excluant du code source public, par exemple dans un fichier .env.
• Tester avec un outil dédié comme Postman ou Insomnia avant d'écrire le code, pour valider le comportement de l'API.