Comprendre les API REST et leur utilisation : le guide essentiel

Un développeur m'a écrit la semaine dernière, un peu paniqué : son nouveau prestataire venait de facturer trois jours de "réunion d'alignement sur l'architecture des endpoints". Trois jours. Pour discuter de la forme des URL. J'ai relu son message deux fois, et j'ai fini par comprendre le vrai problème : personne dans cette histoire ne savait réellement ce qu'est une API REST, ni pourquoi certaines conventions existent. Alors on remplit le vide avec des réunions.

Comprendre les API REST, ce n'est pas apprendre une syntaxe. C'est saisir une manière de penser les échanges entre programmes. Et quand cette compréhension manque, on paie — en heures, en bugs, en dette technique.

API REST : ce que cache vraiment le terme

Une erreur que je vois revenir sans cesse : confondre API et API REST. Ce n'est pas la même chose, et cette confusion explique une bonne partie des malentendus que je croise en mission.

Une API (interface de programmation applicative) est un contrat. Elle dit : « si tu m'envoies ceci, je te réponds cela ». Ce contrat peut prendre mille formes : une bibliothèque qu'on appelle en local, un protocole binaire propriétaire, un fichier échangé par FTP. Une API n'a rien d'obligatoirement web.

REST, lui, est un style architectural. Le terme vient de Roy Fielding, qui l'a formalisé dans sa thèse de doctorat en 2000, en même temps qu'il participait à la conception du protocole HTTP. Une API REST est donc une API qui respecte ce style. On dit aussi RESTful, et franchement, les deux termes sont interchangeables dans la conversation courante.

Pourquoi le mot « représentation » change tout

REST est l'acronyme de REpresentational State Transfer, qu'on traduit maladroitement par « transfert d'état représentationnel ». Le mot important est représentation.

Quand vous demandez une ressource à une API REST, vous ne recevez pas la ressource elle-même. Vous recevez une représentation de cette ressource — le plus souvent en JSON, parfois en XML — dans un format que le serveur a choisi. La ressource, elle, reste sur le serveur. C'est une nuance que beaucoup d'articles sautent, et pourtant elle explique pourquoi vous pouvez demander la même chose en JSON ou en XML : ce sont deux représentations de la même chose.

API REST fonctionnement : la mécanique interne

Une requête REST ressemble à une phrase courte. Un verbe, un sujet, parfois un complément. C'est tout.

Le verbe, c'est la méthode HTTP. Le sujet, c'est la ressource, identifiée par une URL. Le complément, ce sont les données envoyées dans le corps de la requête. Et la réponse arrive avec un code de statut qui indique si ça s'est bien passé.

Les verbes HTTP et ce qu'ils signifient vraiment

Il y a quatre méthodes que vous croiserez dans 95 % des cas. Voici ce qu'elles font concrètement :

• GET — lire une ressource. Exemple : GET /articles/42 ramène l'article numéro 42.
• POST — créer une ressource. POST /articles avec un corps JSON crée un nouvel article.
• PUT — remplacer entièrement une ressource. PUT /articles/42 écrase l'article 42 avec ce que vous envoyez.
• DELETE — supprimer. Vous voyez l'idée.
• PATCH — modifier partiellement. Plus récent dans l'usage courant, il ne touche que les champs que vous fournissez.

La différence entre PUT et PATCH est un piège classique. J'ai vu une équipe casser une base de production parce qu'un script de synchronisation utilisait PUT au lieu de PATCH : à chaque synchro, il écrasait des champs qu'il n'était pas censé toucher, parce que le PUT exige de fournir la ressource complète. Leçon retenue, mais chère.

Codes de statut : lire la réponse en un coup d'œil

La réponse d'une API REST commence toujours par un code à trois chiffres. Les familles sont simples à retenir :

1. 2xx — tout va bien. Le 200 OK est le plus fréquent, 201 Created confirme une création.
2. 4xx — l'erreur vient du client. 404 Not Found : la ressource n'existe pas. 401 Unauthorized : vous n'êtes pas authentifié. 429 Too Many Requests : vous envoyez trop de requêtes, on vous limite.
3. 5xx — l'erreur vient du serveur. Un 500, c'est rarement votre faute, et souvent celle d'un collègue.

Une bonne habitude : gérer explicitement au moins le 404 et le 429 dans votre code client. Le premier évite des crashs bêtes, le second évite de vous faire bloquer par un service que vous martelez.

Un exemple concret de requête et de réponse

Voici une requête typique, telle qu'on l'écrirait avec curl :

GET /api/v1/utilisateurs/12 HTTP/1.1
Host: exemple.fr
Authorization: Bearer eyJhbGci...
Accept: application/json

Et la réponse attendue :

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

{
  "id": 12,
  "nom": "Martin",
  "email": "[email protected]"
}

Deux détails structurent toute votre API. D'abord le préfixe /api/v1/ : il permet de faire évoluer le contrat sans casser les clients existants. Ensuite l'en-tête Accept : il dit au serveur quel format vous voulez. Si vous mettez application/xml, une API REST bien conçue vous renvoie du XML. C'est cette flexibilité qu'on appelle négociation de contenu.

Les six contraintes REST : le cœur du sujet

Voici la partie que je ne trouve presque jamais expliquée correctement. REST n'est pas une spécification qu'on suit à la lettre, c'est un style architectural avec six contraintes. Si une API n'en respecte pas au moins quelques-unes, elle n'est pas vraiment REST.

1. Client-serveur

Le client et le serveur sont séparés. Chacun évolue de son côté. Le client n'a aucune idée de comment le serveur stocke les données, et c'est très bien ainsi.

2. Sans état (stateless)

Chaque requête contient tout ce qu'il faut pour être comprise. Le serveur ne se souvient de rien entre deux appels. C'est la contrainte la plus souvent bafouée, souvent sans qu'on s'en rende compte : dès qu'on stocke un contexte de session sur le serveur entre deux appels, on s'éloigne de REST.

3. Cache

Les réponses doivent indiquer si elles peuvent être mises en cache. Un GET /categories qui change une fois par semaine n'a pas besoin d'être recalculé à chaque appel. Bien exploité, le cache divise la charge serveur sans effort.

4. Interface uniforme

Toutes les ressources se manipulent de la même manière. Une URL désigne toujours une ressource, jamais une action. Vous ne verrez donc pas /creerArticle, mais POST /articles. C'est plus qu'une convention : c'est ce qui rend une API devinable.

5. Système en couches

Entre le client et le serveur peuvent s'intercaler un cache, un équilibreur de charge, un proxy. Le client n'a pas à le savoir. Il appelle une URL, il reçoit une réponse.

6. Code à la demande

Le serveur peut, optionnellement, envoyer du code exécutable au client (du JavaScript, par exemple). C'est la seule contrainte facultative, et elle est rarement utilisée dans les API modernes.

API REST ou SOAP, et les alternatives

La question revient sans cesse, surtout de la part de développeurs qui arrivent d'un environnement d'entreprise. Voici un comparatif honnête.

Approche	Format principal	Idéal pour	Point faible
REST	JSON (souvent)	API publiques, applications web et mobiles	Moins adapté aux requêtes complexes à données imbriquées
SOAP	XML strict	Systèmes bancaires, transactions critiques	Verbeux, lourd à mettre en place
GraphQL	JSON	Clients qui veulent exactement les données qu'ils demandent	Cache plus délicat, complexité côté serveur
gRPC	Protobuf (binaire)	Communication interne entre microservices	Peu adapté aux navigateurs, moins lisible à l'œil nu
WebSocket	Divers	Temps réel (chat, jeux, tableaux de bord live)	Pas conçu pour du request/response classique

Mon avis, et je l'assume : pour 80 % des projets web, REST reste le meilleur point de départ. Il est simple, bien outillé, et tout le monde le connaît. GraphQL brille quand le client a des besoins de données très variables. gRPC est imbattable en interne quand la performance compte. SOAP garde sa place là où les contrats sont lourds et stables.

Sécuriser une API REST : le minimum vital

Un endpoint ouvert sur Internet sans protection, c'est une porte. Il faut la fermer, et ce n'est pas sorcier.

Authentification : quel mécanisme choisir

Trois approches dominent aujourd'hui :

• Clé API — un jeton simple envoyé dans un en-tête. Parfait pour un service à service, insuffisant pour authentifier un utilisateur.
• OAuth 2.0 — la référence pour déléguer l'accès sans partager de mot de passe. C'est ce que vous utilisez quand vous autorisez une application tierce à lire vos données.
• JWT — un jeton signé qui contient des informations sur l'utilisateur. Pratique en environnement sans état, à condition de bien gérer son expiration.

Dans tous les cas, HTTPS est non négociable. Un jeton transmis en clair circule en clair, point final.

Limitation de débit et erreurs à ne pas exposer

Le rate limiting protège votre serveur des abus et des boucles infinies côté client. Un code 429 bien renvoyé vaut mieux qu'un serveur qui tombe.

Deuxième règle, souvent oubliée : ne jamais renvoyer de trace technique brute dans une erreur. Un stack trace en production révèle la structure interne de votre application. Un message générique côté client, un log détaillé côté serveur.

Une erreur que j'ai faite

Sur un projet, j'ai intégré une API de paiement sans gérer autre chose que le code 200. Résultat : pendant deux jours, des paiements échouaient silencieusement avec un 402 que mon code ignorait. Les clients ne voyaient rien, nous non plus. On ne l'a découvert qu'à la première facture. Depuis, je traite chaque famille de codes explicitement, même quand « ça marche ».

API REST Java et autres écosystèmes

Côté Java, deux frameworks se partagent la majorité des projets : Spring Boot, avec son module Spring Web, et Quarkus, plus récent et plus léger au démarrage. Spring reste la valeur sûre en entreprise, avec une communauté énorme et une documentation solide. Quarkus séduit pour les déploiements conteneurisés où la rapidité de démarrage compte.

Pour consommer une API REST en Java, la classe HttpClient du JDK (disponible depuis Java 11) suffit pour des besoins simples. Pour des projets plus vastes, des bibliothèques comme OkHttp ou les clients générés depuis une spécification OpenAPI font gagner beaucoup de temps.

Ce qui m'amène à un conseil que je répète souvent : documentez votre API. Une spécification OpenAPI, même minimale, vaut mieux que trois pages de wiki qui dateront dans six mois. Et elle permet de générer des clients automatiquement, dans la plupart des langages.

Par où commencer

Si vous cherchez un cours API REST PDF ou un tutoriel complet, il y en a d'excellents et gratuitement accessibles. Mais avant de suivre un cours, posez-vous une question simple : quel problème voulez-vous résoudre ?

Vous voulez consommer une API existante ? Commencez par en appeler une avec curl, puis avec le langage de votre choix. Vous voulez en concevoir une ? Listez vos ressources avant vos endpoints. La ressource d'abord, le verbe ensuite. C'est l'inverse que font la plupart des débutants, et c'est ce qui produit des URL comme /getUserById, qui trahissent une API pensée à l'envers.

La vraie maîtrise de REST ne vient pas d'un cours, mais de l'usage. Appelez des API, cassez-en, lisez leurs réponses. Les codes de statut finiront par devenir une langue que vous lisez sans réfléchir.

Et si un jour un prestataire vous facture trois jours de réunion pour discuter de la forme des URL, vous saurez au moins de quoi il parle. C'est déjà beaucoup.