Quand une application météo affiche la température de votre ville, elle ne calcule rien elle-même. Elle interroge un serveur distant, reçoit une réponse et l’affiche. Ce dialogue entre deux programmes passe par une API, et dans la grande majorité des cas il s’agit d’une API REST. Voyons concrètement ce que cela signifie.
D’abord, qu’est-ce qu’une API ?
API signifie Application Programming Interface, interface de programmation applicative. C’est un contrat : un programme expose un ensemble d’opérations, décrit comment les demander et ce qu’elles renvoient, et d’autres programmes peuvent les utiliser sans rien connaître de son fonctionnement interne.
Une comparaison souvent utilisée est celle du restaurant. Vous ne pénétrez pas dans la cuisine : vous consultez la carte, passez commande auprès du serveur et recevez votre plat. La carte et le serveur forment l’interface. La cuisine peut changer de matériel ou de personnel sans que cela modifie votre façon de commander.
Ce que veut dire REST
REST signifie Representational State Transfer. Ce n’est ni un langage ni une bibliothèque : c’est un style d’architecture, un ensemble de principes que l’on choisit de suivre lorsqu’on conçoit une API accessible par le web.
Les principes essentiels sont les suivants :
- Architecture client-serveur. Les deux parties sont séparées et évoluent indépendamment.
- Sans état (stateless). Chaque requête contient toutes les informations nécessaires. Le serveur ne conserve pas de mémoire des échanges précédents.
- Interface uniforme. Les mêmes conventions s’appliquent partout, ce qui rend l’API prévisible.
- Ressources identifiées par des URL. Chaque élément manipulable possède sa propre adresse.
- Mise en cache possible. Les réponses peuvent indiquer si elles sont réutilisables, ce qui allège la charge.
La notion de ressource
Dans une API REST, tout tourne autour des ressources : un utilisateur, un article, une commande, un produit. Chaque ressource est désignée par une URL, et la convention veut que l’on utilise des noms au pluriel plutôt que des verbes.
/articles → tous les articles /articles/42 → l'article dont l'identifiant est 42 /articles/42/commentaires → les commentaires de cet article
Une erreur fréquente chez les débutants consiste à mettre l’action dans l’URL, par exemple /supprimerArticle/42. Dans le style REST, l’action n’est pas dans l’adresse : elle est exprimée par la méthode HTTP employée.
Les méthodes HTTP
Le protocole HTTP fournit un petit vocabulaire de verbes, et REST s’appuie dessus.
| Méthode | Rôle | Exemple |
|---|---|---|
| GET | Lire une ou plusieurs ressources | GET /articles/42 |
| POST | Créer une nouvelle ressource | POST /articles |
| PUT | Remplacer entièrement une ressource | PUT /articles/42 |
| PATCH | Modifier partiellement une ressource | PATCH /articles/42 |
| DELETE | Supprimer une ressource | DELETE /articles/42 |
Deux propriétés importantes distinguent ces méthodes. GET est dit sûr : il ne doit rien modifier sur le serveur. GET, PUT et DELETE sont idempotents : répéter la même requête plusieurs fois produit le même résultat final. POST ne l’est pas, ce qui explique l’avertissement du navigateur lorsqu’on rafraîchit une page après l’envoi d’un formulaire.
Les codes de statut
Chaque réponse contient un code numérique qui indique ce qui s’est passé. Ils sont regroupés par familles.
| Famille | Signification | Exemples courants |
|---|---|---|
| 2xx | Succès | 200 OK, 201 Créé, 204 Pas de contenu |
| 3xx | Redirection | 301 Déplacé définitivement, 304 Non modifié |
| 4xx | Erreur du client | 400 Requête invalide, 401 Non authentifié, 403 Interdit, 404 Introuvable |
| 5xx | Erreur du serveur | 500 Erreur interne, 503 Service indisponible |
La distinction entre 4xx et 5xx est utile au quotidien : une erreur 4xx signifie que la requête envoyée pose problème, une erreur 5xx que le serveur a échoué à la traiter. Elle oriente immédiatement le débogage.
Le format des données
REST n’impose aucun format, mais JSON s’est imposé dans la pratique. Il est lisible par un humain, facile à produire et à interpréter dans presque tous les langages.
{
"id": 42,
"titre": "Introduction aux API",
"auteur": "Marie Dupont",
"publie": true
}
Le client indique le format qu’il souhaite recevoir grâce à l’en-tête Accept, et le serveur précise le format envoyé avec Content-Type.
Quelques bonnes pratiques
- Utiliser des noms, pas des verbes, dans les URL, et rester cohérent sur tout le service.
- Prévoir la pagination. Renvoyer cent mille éléments d’un coup n’est jamais une bonne idée : des paramètres comme
?page=2&limite=50résolvent le problème. - Versionner l’API. Un préfixe comme
/v1/permet de faire évoluer le service sans casser les applications existantes. - Renvoyer des messages d’erreur utiles. Un code 400 accompagné d’une explication précise fait gagner un temps considérable.
- Sécuriser les échanges. HTTPS systématiquement, et une authentification adaptée pour les opérations sensibles.
- Documenter. Une API sans documentation est une API que personne n’utilisera correctement.
Comment s’exercer
La meilleure façon de comprendre reste d’essayer. De nombreuses API publiques permettent de faire des requêtes de lecture sans inscription, et un simple navigateur suffit pour une requête GET. Pour les autres méthodes, des outils spécialisés ou la ligne de commande avec curl font très bien l’affaire.
Observez ce que vous recevez : le code de statut, les en-têtes, la structure du JSON. Ce sont exactement les éléments que vous manipulerez ensuite dans votre propre code.
Conclusion
Une API REST n’est finalement qu’une convention partagée : des ressources identifiées par des URL, des verbes HTTP pour agir dessus, des codes de statut pour décrire le résultat et du JSON pour transporter les données. Cette simplicité explique sa domination sur le web moderne.
Si vous souhaitez approfondir le développement back-end, la programmation web ou les bases de données, Cursa propose des cours gratuits qui prolongent naturellement ces notions.
