API REST : comprendre et utiliser les interfaces web facilement

Un client m'appelle un mardi matin, assez agacé. Sa boutique en ligne affiche des stocks faux depuis deux jours. Son prestataire lui répond : « c'est l'API ». Il me rapporte la phrase sans comprendre ce qu'elle veut dire. Je la comprends très bien, et elle m'énerve à chaque fois, parce qu'elle ne veut rien dire : une API ne tombe pas en panne toute seule. C'est un contrat. Quand le contrat casse, c'est qu'on a changé une clause sans prévenir l'autre partie. Là, en trois minutes, on a trouvé : le développeur avait renommé le champ quantity en qty dans la réponse d'une API REST. La boutique, elle, continuait à lire quantity, tombait sur undefined, et affichait zéro partout. Une lettre de différence, deux jours de ventes faussées.

Cet article, c'est un peu la conversation que j'aurais aimé avoir avec ce prestataire. Comprendre ce qu'est une API REST, comment ça marche vraiment, et comment l'utiliser sans se faire piéger.

API REST : comprendre et utiliser les interfaces web sans y passer la nuit

Posons la base proprement, parce que le mot « API » est aujourd'hui utilisé pour tout et n'importe quoi.

Une API (Application Programming Interface) est un point de contact entre deux logiciels. Vous lui envoyez une demande formatée, elle vous renvoie une réponse formatée. Vous ne savez pas ce qui se passe à l'intérieur, et c'est très bien ainsi. Votre carte bancaire est une API : vous glissez la carte, vous composez un code, vous recevez un « oui » ou un « non ». Tout le reste — les serveurs, les bases, les vérifications — vous échappe.

La réponse courte à la question « API REST définition »

Une API REST est une API exposée sur le web, qui respecte un ensemble de principes : les données sont des ressources identifiées par des URL, on agit dessus avec les méthodes HTTP, et le serveur ne garde aucun souvenir de vos requêtes précédentes. « REST » signifie Representational State Transfer, et cette expression vient de la thèse de Roy Fielding, publiée en 2000. C'est à peu près tout ce que la majorité des articles vous diront. Passons à ce qui compte.

Différence entre API et API REST : où se situe la frontière ?

Je pose souvent la question en entretien technique, et les réponses sont révélatrices. Une API, c'est le concept général : n'importe quelle bibliothèque de code peut exposer une API. Une API REST, c'est un sous-ensemble très précis, avec trois contraintes qui font toute la différence :

• Client-serveur : les deux côtés évoluent séparément. Vous pouvez refondre l'interface utilisateur sans toucher au back-end.
• Sans état (stateless) : le serveur ne se souvient de rien entre deux appels. Chaque requête repart de zéro.
• Interface uniforme : les mêmes verbes HTTP produisent toujours le même type d'effet, quelle que soit la ressource visée.

Cette deuxième contrainte, c'est celle qui déroute au début. « Comment le serveur sait que c'est bien moi ? » Il ne le sait pas. Vous le lui dites à chaque appel, en transmettant votre jeton d'authentification dans chaque requête. C'est fastidieux, c'est un peu bête, et c'est précisément ce qui rend le système scalable : n'importe quel serveur du parc peut traiter votre demande, sans avoir besoin de retrouver la session stockée ailleurs.

Le fonctionnement concret d'une API REST

Vous envoyez une requête HTTP. Elle contient quatre éléments : une URL, une méthode, des en-têtes, et parfois un corps. La réponse contient un code de statut, des en-têtes, et souvent un corps JSON.

Prenons un cas réel. Une boutique veut récupérer la fiche d'un produit identifié par 4821. La requête ressemble à ça :

GET https://api.boutique.fr/v1/produits/4821
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Accept: application/json

Et la réponse, si tout va bien :

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

{
  "id": 4821,
  "nom": "Chaise pliante",
  "prix": 39.90,
  "stock": 12
}

Voilà. Une API REST, c'est ça. Pas de magie, pas de framework obscur, pas de protocole exotique. Juste du HTTP que votre navigateur maîtrise depuis trente ans.

Les quatre verbes à connaître par cœur

1. GET pour lire. Ne modifie rien. Doit être idempotent : appeler dix fois de suite renvoie le même résultat.
2. POST pour créer. Chaque appel produit une nouvelle ressource. Rejouer la requête crée un doublon.
3. PUT pour remplacer intégralement une ressource existante. PATCH pour en modifier seulement un morceau.
4. DELETE pour supprimer.

J'ai déjà vu une équipe utiliser GET pour déclencher l'envoi d'un e-mail de confirmation. Franchement, ça marche… jusqu'au jour où un préchargeur de lien décide d'explorer tous les liens d'une page. Résultat : 340 e-mails envoyés en trois minutes à la même personne. Le prestataire a mis deux jours à comprendre. Un GET ne doit jamais modifier l'état du serveur. Jamais.

Les codes de statut à lire en premier

Quand quelque chose casse, personne ne pense à regarder ça en premier, et pourtant tout est là :

Code	Signification	Ce que ça veut dire pour vous
200	OK	La requête a abouti. Le contenu est dans le corps.
201	Created	La ressource a bien été créée (typiquement après un POST).
400	Bad Request	Votre requête est mal formée. Vérifiez le JSON envoyé.
401	Unauthorized	Jeton absent, expiré ou invalide. C'est très souvent ça.
403	Forbidden	Vous êtes identifié, mais pas autorisé à faire ça.
404	Not Found	L'URL ne correspond à rien. Faute de frappe ?
429	Too Many Requests	Vous avez dépassé le quota. Ralentissez.
500	Internal Server Error	C'est le serveur qui casse. Vous n'y pouvez rien, prévenez le fournisseur.

Retenez la règle : 4xx, c'est votre faute. 5xx, c'est la leur. Cette distinction vous économise des heures de discussion stérile avec un support technique.

API REST exemple : consommer une API depuis une page web

Vous êtes développeur front-end et vous voulez récupérer la liste des produits ? En JavaScript moderne, ça tient en cinq lignes :

const reponse = await fetch('https://api.boutique.fr/v1/produits', {
  headers: { 'Authorization': 'Bearer ' + jeton }
});

if (!reponse.ok) throw new Error('Erreur ' + reponse.status);
const produits = await reponse.json();

Trois pièges dans ces cinq lignes. Le premier : fetch ne rejette pas la promesse en cas d'erreur HTTP. Un 404 renvoie une promesse résolue. Il faut tester reponse.ok manuellement. Beaucoup de développeurs l'ignorent et passent des heures à chercher pourquoi leur code continue alors que l'API renvoie 500.

Le deuxième : CORS. Si votre page et l'API ne sont pas sur le même domaine, votre navigateur va bloquer la réponse, sauf si le serveur envoie un en-tête Access-Control-Allow-Origin adapté. C'est une protection côté navigateur, pas une erreur de votre code. Ne cherchez pas le bug dans votre fetch, il n'y est pas.

Le troisième : la pagination. Une API REST sérieuse ne renvoie pas 40 000 produits d'un coup. Elle en renvoie 50 et vous indique comment demander la suite. Regardez les en-têtes de réponse (Link) ou les paramètres d'URL (?page=2&limit=50). Si vous oubliez ce détail, votre tableau de bord affichera les 50 premiers éléments et vous croirez que la base est tronquée. Je l'ai cru pendant une demi-journée, sur mon premier projet d'intégration.

Authentification : le passage obligé

La clé API, c'est l'option la plus simple, et la plus risquée. Vous mettez une chaîne secrète dans vos en-têtes, et c'est terminé. Le problème, c'est qu'une clé API dans du code JavaScript côté client est visible par n'importe qui. Ouvrez la console, tapez network, regardez. Ne faites jamais ça pour des données sensibles.

Pour un vrai utilisateur, on passe par OAuth 2.0, généralement en flux Bearer token. L'utilisateur autorise votre application une fois, vous recevez un jeton d'accès à durée limitée, et vous le présentez à chaque requête. Les jetons JWT, eux, contiennent les informations de l'utilisateur directement dans leur payload signé, ce qui évite un aller-retour en base à chaque appel. C'est pratique, et c'est un terrain glissant si la signature n'est pas vérifiée.

Un conseil que je donne toujours : mettez les jetons dans un cookie httpOnly, jamais dans le localStorage. Le localStorage est lisible par la moindre ligne de JavaScript injectée dans votre page. Je sais, c'est plus pénible à mettre en place. Faites-le quand même.

API REST ou SOAP ? Et GraphQL dans tout ça ?

La question revient souvent, et elle mérite une réponse plus nuancée que « REST c'est moderne, SOAP c'est has been ».

La vraie différence entre REST et SOAP

SOAP est un protocole. Il impose un format (XML), une enveloppe, un contrat WSDL, et souvent des outils dédiés côté client. REST est un style architectural : il ne vous impose rien sur le format (JSON, XML, HTML, peu importe), rien sur les outils, rien sur le contrat. C'est une contrainte légère posée sur du HTTP qui existait déjà.

Est-ce que SOAP est mort pour autant ? Non. Dans les environnements bancaires et les systèmes publics, il survit très bien, parce qu'il apporte une sécurité de niveau message et une formalisation de contrat que REST ne propose pas nativement. J'ai dû intégrer une API SOAP il y a deux ans pour un client du secteur public. C'était lourd, mais la documentation générée automatiquement depuis le WSDL était irréprochable.

Faut-il passer à GraphQL ?

GraphQL résout un problème réel : le sur-fetching. Une API REST vous renvoie une fiche produit complète alors que vous vouliez juste le prix. GraphQL vous laisse demander exactement les champs dont vous avez besoin.

Mais ça vient avec un coût : plus de complexité côté serveur, une couche de cache à repenser entièrement (les requêtes GraphQL sont majoritairement en POST, ce qui casse le cache HTTP classique), et un risque de requêtes abusives si vous ne plafonnez pas la profondeur d'exploration. Pour une petite application avec trois écrans, REST reste largement suffisant. Pour un front-end complexe avec quinze composants qui réclament chacun des morceaux différents de la même donnée, GraphQL mérite sérieusement l'évaluation.

Erreurs courantes et débogage d'une API REST

J'ai compilé, après plusieurs années, les erreurs que je vois revenir systématiquement chez les développeurs qui débutent sur les API REST.

• Confondre URL et identifiant. /produits/4821 désigne une ressource. /getProduit?id=4821 trahit une habitude de PHP procédural. Les deux fonctionnent, mais le second est un contresens.
• Placer un verbe dans l'URL. /creerProduit en POST est redondant : la méthode HTTP dit déjà ce que fait la requête.
• Envoyer un corps JSON sans Content-Type. Le serveur ne saura pas le parser et renverra un 400 que vous mettrez vingt minutes à comprendre.
• Ne pas gérer le 429. En production, une API publique vous rate-limite. Sans mécanisme de retry avec backoff exponentiel, vous vous faites bloquer bêtement.
• Faire confiance à la réponse sans valider. Un champ peut être null alors que votre code suppose une chaîne.

Les outils de débogage qui valent le coup

Pour explorer une API, je commence par la documentation (souvent une page Swagger ou OpenAPI), puis j'ouvre l'onglet Réseau du navigateur. Ce dernier est sous-utilisé : il montre la requête brute, les en-têtes réels, le temps de réponse, et le corps exact. Avant d'ouvrir un outil externe, commencez par là.

Pour des tests répétés, Postman ou Insomnia restent pratiques, surtout pour rejouer une collection de requêtes. Mais attention : si vous ne testez que dans Postman, vous ne verrez jamais les problèmes CORS, qui n'existent que dans le contexte du navigateur. J'ai perdu une journée entière à chercher un bug invisible dans Postman, alors qu'il apparaissait en une seconde dans la console du navigateur.

Ce qu'il faut retenir, en une phrase

Une API REST n'est pas un objet mystérieux : c'est du HTTP avec des conventions. Des URL qui désignent des choses, des verbes qui disent quoi en faire, des codes de statut qui racontent l'histoire de la requête, et un jeton qui prouve qui vous êtes.

Le vrai apprentissage, il n'est pas dans la théorie. Il est dans le moment où vous ouvrez l'onglet Réseau, où vous voyez le 401 que vous n'attendiez pas, où vous réalisez que votre Content-Type manquait. Ce moment-là, vous ne l'oublierez pas.

Et la prochaine fois qu'un prestataire vous dit « c'est l'API », vous saurez au moins quel code de statut lui demander.