API REST : comprendre et consommer des services web

Quand votre application météo affiche 14 degrés à Nantes, quand un site e-commerce calcule vos frais de livraison ou quand votre CRM récupère automatiquement le SIRET d’un client, il y a presque toujours une API REST derrière. Le mot fait peur aux débutants, alors que le principe tient dans une phrase : un programme pose une question à un serveur, dans un format convenu, et reçoit une réponse lisible par une machine. Pas de magie. Un peu de vocabulaire, trois ou quatre réflexes, et vous serez capable d’interroger n’importe quel service web d’ici la fin de cet article.

Une API, c’est un guichet, pas une base de données

#

API signifie Application Programming Interface. Traduction libre : une interface qui permet à deux logiciels de discuter sans connaître les entrailles l’un de l’autre. L’image du guichet marche bien. Vous ne rentrez pas dans les archives de la mairie pour chercher votre acte de naissance, vous remplissez un formulaire au guichet et on vous tend le document. L’API, c’est le guichet. Ce qu’il y a derrière (une base PostgreSQL, un vieux mainframe, trois microservices) ne vous regarde pas.

REST, pour Representational State Transfer, est une façon de concevoir ce guichet. Ce n’est ni un langage ni un logiciel, plutôt un ensemble de conventions posées par Roy Fielding en 2000 dans sa thèse. Et ces conventions ont gagné : dans le dernier rapport annuel de Postman sur l’état des API, 93 % des équipes interrogées déclarent utiliser REST. GraphQL, souvent présenté comme son successeur, plafonne autour d’un tiers, et presque toujours en complément de REST plutôt qu’à sa place.

Les idées clés de REST sont peu nombreuses :

• Tout est ressource. Un utilisateur, une commande, une commune : chaque objet a son adresse (une URL).
• On agit sur ces ressources avec les verbes HTTP, les mêmes que ceux qu’utilise votre navigateur.
• Chaque requête se suffit à elle-même. Le serveur ne se souvient pas de vous entre deux appels (on dit qu’il est stateless). Si vous devez vous authentifier, vous renvoyez votre clé à chaque fois.
• Les réponses sont dans un format standard, en pratique du JSON dans l’immense majorité des cas.

Prérequis : aucun pour comprendre les concepts. Pour les exemples de code, des bases en JavaScript ou en Python aident. Si ce n’est pas encore le cas, le guide pour apprendre le développement web pose le décor.

Anatomie d’une requête HTTP

#

Une requête REST se compose de quatre éléments. Prenons un exemple réel, celui de l’API Géo du gouvernement, gratuite et sans inscription :

GET https://geo.api.gouv.fr/communes?nom=Lyon&fields=nom,code,population&limit=2
Accept: application/json

Décortiquons.

La méthode (GET) dit ce que vous voulez faire. L’URL désigne la ressource : ici la collection communes, filtrée par des paramètres de requête placés après le ? et séparés par des &. Les en-têtes (headers) transportent des métadonnées : le format attendu, un jeton d’authentification, la langue. Le corps (body), absent ici, contient les données envoyées quand on crée ou modifie quelque chose.

Et la réponse du serveur ressemble à ça :

[
  { "nom": "Lyon", "code": "69123", "population": 519127 },
  { "nom": "Cognat-Lyonne", "code": "03080", "population": 706 }
]

Des crochets pour une liste, des accolades pour un objet, des paires clé/valeur. Si vous savez lire un tableau Excel, vous savez lire du JSON, c’est juste présenté autrement.

[Schéma à insérer : le trajet d’une requête, du client au serveur puis retour, avec méthode, URL, en-têtes, corps et code de statut annotés]

Les verbes HTTP à connaître

#

Remarquez la logique des URL : un nom au pluriel pour la collection (/articles), un identifiant pour l’élément (/articles/42). Une API bien conçue n’a pas d’URL du genre /getArticle?id=42 ou /supprimerArticle. Le verbe est déjà dans la méthode, inutile de le répéter.

Les codes de statut : ce que le serveur essaie de vous dire

#

Chaque réponse arrive avec un code à trois chiffres. Le premier chiffre suffit à savoir de quel côté se trouve le problème, ce qui fait gagner un temps fou au débogage.

Au début, je mélangeais systématiquement 401 et 403, et je ne suis pas le seul. 401 veut dire « je ne sais pas qui vous êtes » : clé absente ou invalide. 403 veut dire « je sais qui vous êtes, mais vous n’avez pas le droit ». Et le 429, vous le rencontrerez tôt ou tard en bouclant un peu trop vite sur une API gratuite : vous avez dépassé le quota, il faut ralentir.

Attention : certaines API mal fichues renvoient un 200 avec un message d’erreur dans le corps. Frustrant, mais ça existe. Lisez toujours la documentation pour savoir comment le service signale ses erreurs.

Tester une API sans écrire une ligne de code

#

Premier réflexe, avant même d’ouvrir l’éditeur : appeler l’API à la main. On découvre la tête des réponses, et surtout on s’épargne ce grand classique, passer une heure sur un script parfaitement correct alors que la faute de frappe était dans l’URL.

Le navigateur suffit pour les requêtes GET simples. Collez l’URL de l’API Géo dans la barre d’adresse, Firefox affiche même le JSON de façon lisible.

curl, en ligne de commande, est installé d’office sur macOS, Linux et Windows 10 ou plus récent :

# -s masque la barre de progression, -i affiche aussi les en-têtes de réponse
curl -si "https://geo.api.gouv.fr/communes?nom=Nantes&fields=nom,population"

Un client graphique devient vite indispensable dès qu’on enchaîne les appels, qu’on gère des jetons ou qu’on envoie des POST. Le paysage a pas mal bougé cette année :

Depuis mars 2026, le plan gratuit de Postman ne couvre plus qu’un seul utilisateur, et beaucoup d’équipes ont migré vers Bruno dans la foulée. Personnellement, c’est aussi ce que je conseille à un débutant aujourd’hui : il est léger, il ne réclame pas de compte, et vos collections vivent à côté de votre code. Si vous avez suivi notre tutoriel Git et GitHub pour les débutants, vous verrez vite l’intérêt.

Consommer une API en JavaScript avec fetch

#

Côté navigateur comme côté Node.js (depuis la version 18), fetch est disponible sans rien installer. Voici une petite fonction qui cherche une commune et affiche sa population :

async function chercherCommune(nom) {
  // encodeURIComponent protège les accents et les espaces dans l'URL
  const url = `https://geo.api.gouv.fr/communes?nom=${encodeURIComponent(nom)}&fields=nom,code,population&limit=5`;

  const reponse = await fetch(url);

  // fetch ne lève PAS d'erreur sur un 404 ou un 500 : il faut vérifier soi-même
  if (!reponse.ok) {
    throw new Error(`Erreur HTTP ${reponse.status}`);
  }

  const communes = await reponse.json(); // conversion du JSON en objets JS
  for (const c of communes) {
    console.log(`${c.nom} (${c.code}) : ${c.population ?? "?"} habitants`);
  }
}

chercherCommune("Saint-Étienne").catch(console.error);

Le commentaire sur reponse.ok n’est pas là pour faire joli. C’est le piège numéro un avec fetch : une réponse 404 est considérée comme une requête réussie (le serveur a bien répondu), seule une panne réseau déclenche une exception. Si vous oubliez ce test, votre code tentera de parser une page d’erreur et vous chercherez le bug pendant une demi-heure. Tout le reste (async, await, try/catch) est détaillé dans notre article sur les concepts essentiels de JavaScript moderne.

Pour envoyer des données, on précise la méthode, les en-têtes et le corps. JSONPlaceholder, une fausse API gratuite faite pour s’entraîner, accepte les POST sans rien enregistrer réellement :

const nouvelArticle = { title: "Mon premier POST", body: "Ça marche !", userId: 1 };

const reponse = await fetch("https://jsonplaceholder.typicode.com/posts", {
  method: "POST",
  headers: { "Content-Type": "application/json" }, // on annonce du JSON
  body: JSON.stringify(nouvelArticle),             // objet JS -> texte JSON
});

console.log(reponse.status);        // 201 : ressource créée
console.log(await reponse.json());  // l'objet renvoyé, avec un id attribué

Consommer une API en Python avec requests

#

En Python, la bibliothèque requests reste la référence, même si httpx gagne du terrain pour le code asynchrone. Installation : pip install requests.

import requests

url = "https://geo.api.gouv.fr/communes"
params = {"nom": "Saint-Étienne", "fields": "nom,code,population", "limit": 5}

# requests construit l'URL et encode les accents à votre place
reponse = requests.get(url, params=params, timeout=10)

# lève une exception si le code est 4xx ou 5xx
reponse.raise_for_status()

for commune in reponse.json():
    print(f"{commune['nom']} ({commune['code']}) : {commune.get('population', '?')} habitants")

Deux détails qui distinguent un script amateur d’un script fiable. Le paramètre timeout d’abord : sans lui, votre programme peut attendre indéfiniment une réponse qui ne viendra jamais. Et raise_for_status(), qui fait en une ligne le travail du test reponse.ok côté JavaScript. Si Python est encore nouveau pour vous, notre guide Python pour débutants vous donnera les bases nécessaires en quelques soirées.

Authentification, quotas et pagination : les réalités du terrain

#

Les API de démonstration sont ouvertes à tous. Dans la vraie vie, la plupart demandent de s’identifier, et c’est là que les débutants coincent.

La clé d’API est la méthode la plus simple. Vous créez un compte, le service vous donne une chaîne de caractères, et vous la transmettez dans un en-tête (souvent Authorization: Bearer VOTRE_CLÉ ou X-API-Key). OAuth 2.0 entre en jeu quand une application agit au nom d’un utilisateur, le fameux bouton « Se connecter avec Google ». Plus complexe, mais les bibliothèques font l’essentiel du travail.

import os
import requests

cle = os.environ["MON_API_KEY"]  # lue depuis l'environnement, jamais écrite en dur

reponse = requests.get(
    "https://api.exemple.com/v1/commandes",
    headers={"Authorization": f"Bearer {cle}"},
    timeout=10,
)

Attention : une clé d’API ne se colle jamais dans le code que vous publiez sur GitHub. Des robots scannent les dépôts publics en permanence et une clé exposée peut être exploitée en quelques minutes, avec parfois une facture à la clé si le service est payant. Variables d’environnement ou fichier .env ignoré par Git, sans exception.

Les quotas (rate limiting) limitent le nombre d’appels par minute ou par jour. Lisez les en-têtes de réponse, beaucoup d’API y indiquent le nombre de requêtes restantes. En cas de 429, attendez avant de relancer, et augmentez le délai à chaque nouvel échec.

La pagination, enfin : une API ne vous renverra jamais 50 000 résultats d’un coup. Elle découpe en pages, via des paramètres comme page et per_page, ou limit et offset, ou encore un curseur fourni dans la réponse précédente. Chaque API a sa façon de faire, d’où l’intérêt de toujours commencer par la documentation.

Astuce : pour vous entraîner, la plateforme api.gouv.fr recense des dizaines d’API publiques françaises (adresses, entreprises, jours fériés, qualité de l’air). Données réelles, documentation en français, et la plupart sont gratuites. Idéal pour un premier projet qui a du sens.

Et maintenant, que faire ?

#

Vous avez les bases : ressources et URL, verbes HTTP, codes de statut, JSON, et deux façons de faire un appel en code. Pour ancrer tout ça, rien ne vaut un mini-projet. Quelques idées réalisables en un week-end :

1. Une page web qui affiche la population et le département d’une commune saisie par l’utilisateur, avec l’API Géo.
2. Un script Python qui récupère les jours fériés de l’année et les ajoute à un fichier CSV.
3. Un tableau de bord personnel qui interroge une API météo gratuite chaque matin.

L’étape suivante, c’est de passer de l’autre côté du guichet : créer votre propre API avec Express (Node.js) ou FastAPI (Python). Vous verrez alors toutes ces conventions sous un autre angle, et vous comprendrez pourquoi les bonnes API sont si agréables à utiliser, et les mauvaises si pénibles.