API REST : comprendre et consommer une API sans se perdre

Vous tapez sur une URL qui finit par /users/42/repos, vous recevez une liste de dépôts GitHub au format JSON, et votre script affiche les noms. Pas de navigateur, pas de clic humain. C'est ça, consommer une API REST. Et si je commence par cet exemple précis, c'est parce qu'il cristallise tout ce que les tutos ratent : on vous explique pendant 2 000 mots ce qu'est REST, puis on vous lâche au moment où il faut vraiment faire l'appel.

L'autre moitié du problème, c'est le vocabulaire. API REST, RESTful, API Web, endpoint, ressource… On empile les termes sans jamais dire lequel désigne quoi. Je vais être direct : une bonne partie de ces mots sont interchangeables, et les confusions viennent souvent de gens qui répètent une définition apprise sans jamais avoir lu une réponse HTTP avec un code 429.

API REST : la définition qu'on aurait dû vous donner tout de suite

Une API est une interface : un ensemble de règles qui permet à un programme d'en appeler un autre sans connaître son fonctionnement interne. Rien de plus. Une API REST est une API qui suit le style architectural REST pour exposer ses fonctionnalités.

Et là, la nuance que 90 % des articles zappent.

REST est un style, pas une norme

Roy Fielding a décrit REST dans sa thèse de doctorat, en 2000. Il a formulé six contraintes. Le respect de toutes ces contraintes fait d'une API une API REST au sens strict. Le respect de quelques-unes fait une API « RESTish » — ce qu'on croise en réalité chez la grande majorité des fournisseurs.

Les contraintes qui pèsent le plus dans la pratique :

• Une architecture client-serveur, avec séparation des responsabilités.
• Une communication sans état (stateless) : chaque requête porte tout ce qu'il faut pour être comprise.
• Une interface uniforme, où les ressources sont identifiées par des URI et manipulées avec un jeu d'opérations standard.
• Un système en couches, où le client ne sait pas s'il parle au serveur final ou à un intermédiaire.

Cette histoire de stateless est celle qui change le plus votre code. Si le serveur ne garde aucune mémoire de votre session, vous devez renvoyer à chaque appel tout ce qui identifie votre contexte : un jeton, un identifiant, une clé. Vous ne pouvez pas « vous connecter une fois » et enchaîner tranquillement.

Quelle est la différence entre API et API REST ?

Une API est le genre, une API REST est une espèce. Toutes les API REST sont des API, l'inverse est faux. Une API peut très bien s'appuyer sur SOAP, sur GraphQL, sur gRPC, ou sur un protocole maison sans le moindre rapport avec HTTP. Quand on parle d'API REST, on parle presque toujours d'API qui utilisent HTTP comme transport, avec des URL comme identifiants de ressources et des verbes HTTP comme opérations.

Comment ça marche vraiment : une requête, une réponse, un code

Oubliez la théorie un instant. Une requête HTTP vers une API REST contient toujours quatre éléments : une méthode (GET, POST, PUT, PATCH, DELETE), une URL, des en-têtes (headers), et parfois un corps (body). La réponse contient un code de statut, des en-têtes, et un corps — le plus souvent en JSON, parfois en XML.

C'est tout. Si vous avez compris ça, vous savez lire n'importe quelle documentation d'API. Le reste est du remplissage.

Les codes de statut : votre meilleur outil de debug

Je vois régulièrement des développeurs qui passent 40 minutes à chercher pourquoi un appel échoue, en regardant le corps de la réponse, alors que l'en-tête HTTP affiche un code 401. Lisez toujours le code en premier.

Les codes à connaître par cœur

Code	Signification	Ce que vous devez faire
200	OK	Lire le corps, c'est bon.
201	Created	Une ressource a été créée ; son URL est souvent dans l'en-tête Location.
400	Bad Request	Le corps envoyé est probablement mal formé ou un champ obligatoire manque.
401	Unauthorized	Le jeton ou la clé manque, ou est invalide.
403	Forbidden	Authentifié mais pas autorisé pour cette ressource précise.
404	Not Found	L'URL ne correspond à rien côté serveur.
429	Too Many Requests	Vous avez dépassé le quota. Lisez l'en-tête Retry-After.
500	Internal Server Error	Bug côté serveur. Retentez avec un backoff, puis remontez le problème.

Le 429 est celui qui m'a coûté le plus cher. J'avais écrit un script de synchronisation qui tournait toutes les nuits, sans limitation de débit. Semaine 1 : tout va bien. Semaine 3 : l'API renvoie des 429 en série, le script se plante, et je ne m'en rends compte qu'en découvrant un tableau de bord vide le lundi matin. Depuis, je code systématiquement trois retries avec un backoff exponentiel, et j'ai arrêté de croire que « ça marche en local » veut dire quoi que ce soit.

Consommer une API REST : le guide pratique

Consommer, c'est le verbe qui manque à la plupart des articles sur le sujet. Ils expliquent la conception, l'exposition côté serveur, mais rarement l'appel côté client. Voilà donc concrètement comment on fait.

Trois façons d'appeler une API, du plus nu au plus habillé

En ligne de commande, avec curl. Idéal pour tester un endpoint avant d'écrire une seule ligne de code :

curl -H "Authorization: Bearer VOTRE_JETON" \
     https://api.example.com/users/42/repos

En JavaScript côté navigateur, avec fetch. Pas de bibliothèque externe :

const reponse = await fetch(
  "https://api.example.com/users/42/repos",
  { headers: { Authorization: "Bearer " + jeton } }
);
if (!reponse.ok) throw new Error("Code " + reponse.status);
const donnees = await reponse.json();

En Python, avec la bibliothèque requests. Le plus lisible pour un script d'automatisation :

import requests
r = requests.get(
    "https://api.example.com/users/42/repos",
    headers={"Authorization": f"Bearer {jeton}"}
)
r.raise_for_status()
donnees = r.json()

Remarquez qu'aucun de ces trois exemples ne vous dit quelle URL appeler. Ça, c'est le rôle de la documentation de chaque API. Aucune recette magique ne remplace la lecture du schéma.

Authentification : clé API ou OAuth 2 ?

La clé API, c'est une simple chaîne de caractères que vous collez dans un en-tête. Cinq minutes pour la mettre en place, parfait pour un service à service, à condition de ne jamais la mettre dans du code côté client — elle serait visible dans les outils du navigateur en deux clics.

OAuth 2 devient nécessaire dès qu'une application agit au nom d'un utilisateur. Un jeton d'accès révocable, des scopes, un flux de redirection : c'est plus complexe, mais c'est ce qui permet à un utilisateur de retirer un accès sans changer son mot de passe. Si votre intégration doit s'authentifier avec les comptes de vos utilisateurs, vous finirez par passer par OAuth 2. Autant le savoir tôt.

Pagination et quotas : les deux pièges cachés

Une API ne vous renverra jamais 50 000 résultats d'un coup. Elle pagine. Selon les fournisseurs, vous trouverez des paramètres comme ?page=2&per_page=100, ou un curseur opaque fourni dans la réponse. Le second cas est plus courant sur les grosses API, parce qu'il résiste mieux aux insertions de données pendant que vous parcourez les pages.

Le piège classique : boucler sur les pages en incrémentant jusqu'à retomber sur une page vide, en espérant tomber juste. Mauvaise stratégie. Lisez la documentation, identifiez le champ qui signale une page suivante (souvent next ou Link), et arrêtez-vous quand il disparaît.

Sur les quotas, j'ai un chiffre concret : sur un projet où j'appelais une API de facturation en boucle pour rafraîchir un écran, je consommais 18 000 requêtes par jour pour un usage réel d'environ 200. La solution n'était pas technique, elle était produit : mettre en cache les réponses pendant 10 minutes. La consommation est tombée du jour au lendemain. Beaucoup de problèmes de quotas sont en réalité des problèmes de design.

API REST ou SOAP : laquelle choisir ?

SOAP est un protocole avec un contrat strict — WSDL —, un format XML obligatoire, et une lourdeur assumée. REST est un style, avec des formats libres et une légèreté par défaut. SOAP reste pertinent dans quelques niches : la banque, l'assurance, les systèmes industriels où la validation stricte du contrat et la traçabilité sont plus importantes que la vitesse de développement.

Pour tout le reste, REST a gagné. Et ce n'est pas un hasard : un développeur peut appeler une API REST avec curl la première fois qu'il en entend parler. Personne ne fait ça avec SOAP.

Un mot sur GraphQL, puisque la question arrive souvent : c'est une alternative qui corrige certains défauts de REST, notamment le sur-fetch (recevoir 40 champs quand on en veut 3). Mais elle déplace la complexité côté serveur, et pour un usage simple, REST reste plus direct.

Ce que j'aurais aimé savoir en commençant

Trois erreurs qui m'ont coûté du temps, et que je vois se répéter autour de moi.

Confondre URL et ressource. L'URL /users/42/repos ne désigne pas un dossier. C'est un identifiant unique pour une collection de ressources, calculée à chaque appel. Si vous raisonnez en arborescence de fichiers, vous allez chercher des comportements qui n'existent pas.

Ignorer les en-têtes de réponse. Les informations les plus utiles — quota restant, format attendu, lien vers la page suivante — sont souvent dans les en-têtes, pas dans le corps. Prenez l'habitude de les afficher en développement.

Ne pas tester les cas d'erreur. Un script qui ne gère que le cas nominal se plante silencieusement à la première exception. Forcez une 404, forcez une 401, forcez une 429, et regardez ce que fait votre code. C'est dix minutes d'investissement pour des heures de debug économisées.

Ce qui reste, au fond, c'est une chose simple : une API REST, ce n'est pas une technologie à apprendre, c'est une convention à lire. Le meilleur investissement de votre semaine n'est pas un nouveau framework, c'est de passer une heure à lire la documentation d'une API que vous utilisez déjà tous les jours. Vous y trouverez presque toujours un endpoint que vous auriez payé cher pour connaître.