API REST expliquée : ce qui se passe vraiment quand votre appli « appelle une API »

En une phrase

Une API REST n'est qu'un ensemble d'URLs auxquelles un serveur accepte de répondre de façon prévisible, en utilisant le même HTTP que votre navigateur utilise déjà pour charger des pages web. Il n'y a pas de protocole secret séparé — « appeler une API », c'est votre application qui envoie une requête HTTP et lit la réponse, exactement comme un navigateur.

Ce qui rend vraiment ça « REST »

Débarrassez-vous du jargon et l'idée centrale est simple : chaque URL représente une chose — une ressource, comme un utilisateur, une commande, ou une photo — et le verbe HTTP utilisé sur cette URL dit ce que vous voulez lui faire. GET la lit sans rien changer, POST en crée une nouvelle, PUT ou PATCH met à jour une existante, DELETE la supprime. GET /users/42 lit l'utilisateur 42. DELETE /users/42 supprime l'utilisateur 42. Même URL, verbe différent, action complètement différente. Cette association — nom dans l'URL, verbe dans la requête — est la véritable idée fondatrice de REST, rien de plus mystérieux.

Une requête concrète, de bout en bout

Votre application envoie GET https://api.example.com/users/42 avec un en-tête comme Authorization: Bearer <token> prouvant qui pose la question. Le serveur vérifie ce token, cherche l'utilisateur 42, et renvoie une réponse avec un code de statut — 200 pour succès, 404 si cet utilisateur n'existe pas, 401 si votre token n'était pas valide — et un corps, presque toujours du JSON aujourd'hui, contenant les données réelles : {"id": 42, "name": "..."}. Votre application ne voit jamais une base de données ni les entrailles d'un serveur ; elle ne voit que cette réponse structurée et convenue à l'avance.

Ce que les codes de statut communiquent vraiment, et pourquoi ça compte

Les groupes 2xx, 4xx et 5xx signifient chacun quelque chose de distinct. 2xx veut dire que ça a marché. 4xx veut dire que la requête de votre application avait elle-même un problème — mauvais identifiant, authentification manquante. 5xx veut dire que le serveur lui-même a planté en essayant de traiter une requête pourtant parfaitement valide. Cette distinction compte vraiment pour déboguer : un 404 vous dit de vérifier ce que vous demandez, un 500 vous dit que le problème est de leur côté, pas du vôtre — deux étapes suivantes très différentes.

Ce qu'on se trompe souvent

« Une API REST renvoie toujours du JSON » — REST en tant que concept n'exige absolument pas le JSON. Il est antérieur à la domination du JSON comme standard, et peut techniquement renvoyer du XML ou du texte brut tout aussi valablement. Le JSON a simplement gagné le concours de popularité parce qu'il est léger et que chaque langage peut le parser facilement, donc il est devenu le standard quasi universel en pratique, pas une exigence de REST lui-même.

Une nuance à connaître

Tout ce qu'on appelle « API REST » dans la nature n'est pas vraiment du REST puriste selon la définition académique stricte. La plupart des API réelles assouplissent légèrement les règles — en sautant certaines contraintes plus strictes de la définition originale — et personne dans l'industrie ne considère ça comme un vrai problème. « RESTful », en usage courant et quotidien, veut simplement dire « une API JSON-sur-HTTP organisée autour de ressources et de verbes », ce qui est la définition pratique à connaître plutôt que l'académique.