> Comprendre une API REST : ressources, verbes HTTP, codes de statut, JSON, conception d'endpoints, authentification et versionnement, avec un exemple concret en fetch. *Source : https://coder-studio.com/tutoriels/api-rest-guide/* --- [// Web](https://coder-studio.com/tutoriels/) # API REST : principes et bonnes pratiques Par **Kévin Papot** · publié le 16 février 2026 Une **API REST** est aujourd’hui la façon la plus répandue de faire communiquer un front-end, une application mobile ou un service tiers avec un serveur. Derrière l’acronyme (Representational State Transfer) se cache un style d’architecture proposé par Roy Fielding en 2000, qui s’appuie entièrement sur les mécanismes du web : les URL, le protocole HTTP et, le plus souvent, le format JSON. Ce guide décortique les principes fondateurs et les bonnes pratiques pour concevoir des API claires, cohérentes et faciles à consommer. ## Le principe des ressources Le cœur de REST, c’est la notion de **ressource**. Une ressource est une entité métier que l’on peut manipuler : un utilisateur, un article, une commande, un commentaire. Chaque ressource est identifiée par une URL stable. La convention est d’utiliser des **noms au pluriel**, jamais des verbes : ``` GET /articles → la collection d'articles GET /articles/42 → l'article dont l'identifiant est 42 GET /articles/42/commentaires → les commentaires de cet article ``` On évite absolument les URL du type `/getArticle` ou `/creerCommentaire`. L’action n’est pas dans l’URL : elle est portée par le **verbe HTTP**. L’URL décrit _quoi_, la méthode décrit _comment_. ## Les verbes HTTP REST réutilise les méthodes HTTP standard pour exprimer l’intention. Les quatre plus courantes couvrent le fameux CRUD (Create, Read, Update, Delete) : - **GET** : lire une ressource ou une collection. Ne doit jamais modifier de données (méthode _sûre_). - **POST** : créer une nouvelle ressource dans une collection. - **PUT** : remplacer intégralement une ressource existante. - **PATCH** : modifier partiellement une ressource (un ou deux champs). - **DELETE** : supprimer une ressource. Deux propriétés méritent d’être connues. Une méthode est **sûre** si elle ne modifie rien (GET). Elle est **idempotente** si l’appeler plusieurs fois produit le même résultat qu’un seul appel : c’est le cas de GET, PUT et DELETE, mais pas de POST, qui crée une nouvelle entité à chaque appel. ## Les codes de statut La réponse d’une API REST doit toujours renvoyer un **code de statut HTTP** qui reflète fidèlement le résultat. Les regrouper par famille aide à les mémoriser : - **2xx — succès** : `200 OK` (lecture réussie), `201 Created` (ressource créée, avec idéalement un en-tête `Location`), `204 No Content` (succès sans corps, typique d’un DELETE). - **3xx — redirection** : `301 Moved Permanently`, `304 Not Modified` (utile pour le cache). - **4xx — erreur du client** : `400 Bad Request` (requête malformée), `401 Unauthorized` (non authentifié), `403 Forbidden` (authentifié mais pas autorisé), `404 Not Found`, `422 Unprocessable Entity` (validation échouée). - **5xx — erreur du serveur** : `500 Internal Server Error`, `503 Service Unavailable`. Retourner un `200` avec un message d’erreur dans le corps est une mauvaise pratique fréquente : le client ne peut plus s’appuyer sur le code de statut pour réagir automatiquement. ## Le format JSON Le corps des requêtes et des réponses est presque toujours en **JSON**, avec l’en-tête `Content-Type: application/json`. Une réponse typique pour un article ressemble à ceci : ``` { "id": 42, "titre": "Découvrir REST", "auteur": { "id": 7, "nom": "Camille" }, "publie": true, "dateCreation": "2026-02-10T09:30:00Z" } ``` Quelques conventions utiles : rester cohérent sur la casse des clés (camelCase ou snake\_case, mais pas les deux), formater les dates en ISO 8601, et structurer les erreurs de façon prévisible : ``` { "erreur": "validation", "message": "Le champ titre est obligatoire", "champs": ["titre"] } ``` ## Concevoir de bons endpoints Au-delà des ressources de base, quelques pratiques rendent une API agréable à consommer. Pour les **listes**, prévoyez la pagination, le tri et le filtrage via la _query string_ : ``` GET /articles?page=2&taille=20&tri=-dateCreation&publie=true ``` Gérez les **relations** en imbriquant les URL avec parcimonie (`/articles/42/commentaires` reste lisible, mais évitez d’empiler trois niveaux). Documentez systématiquement votre API, idéalement avec une spécification **OpenAPI** qui sert à la fois de contrat et de source pour générer des clients. ## Authentification et sécurité La plupart des API protègent leurs endpoints. Le mécanisme le plus courant s’appuie sur un **jeton** transmis dans l’en-tête `Authorization` : ``` Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6... ``` Les JWT (JSON Web Tokens) sont répandus pour ce type d’authentification sans état. Quelques règles non négociables : servir l’API exclusivement en **HTTPS**, ne jamais exposer de données sensibles dans l’URL (elles finissent dans les logs), et appliquer un _rate limiting_ pour limiter les abus. Pensez aussi à configurer correctement les en-têtes **CORS** si votre API est appelée depuis un navigateur sur un autre domaine. ## Versionner son API Une API vit et évolue. Pour ne pas casser les clients existants lors d’un changement incompatible, on introduit un **numéro de version**. La méthode la plus lisible passe par l’URL : ``` GET /v1/articles GET /v2/articles ``` D’autres préfèrent la négociation par en-tête (`Accept: application/vnd.monapi.v2+json`), plus « pure » au sens REST mais moins pratique à tester. Dans les deux cas, l’important est de fixer une politique claire et de la documenter. ## Exemple concret avec fetch Voici comment consommer une API REST côté navigateur avec l’API `fetch`, en gérant proprement le code de statut : ``` async function creerArticle(titre, contenu) { const reponse = await fetch("https://api.exemple.fr/v1/articles", { method: "POST", headers: { "Content-Type": "application/json", "Authorization": `Bearer ${monToken}` }, body: JSON.stringify({ titre, contenu }) }); if (!reponse.ok) { // reponse.ok est vrai pour les statuts 2xx const erreur = await reponse.json(); throw new Error(erreur.message ?? `Erreur ${reponse.status}`); } return reponse.json(); // l'article créé, avec son id } ``` On retrouve tous les principes : le verbe `POST`, l’URL versionnée pointant vers la collection `/articles`, l’en-tête d’authentification, le corps JSON et la vérification du statut via `reponse.ok`. ## En résumé Une bonne API REST repose sur peu de règles, mais appliquées avec rigueur : des ressources nommées clairement, les bons verbes HTTP, des codes de statut honnêtes, du JSON cohérent, une authentification solide et un versionnement anticipé. Ces conventions partagées sont précisément ce qui rend REST si universel : un développeur qui connaît une API REST sait déjà en consommer mille autres. ## À lire ensuite - [Le JAMstack expliqué simplement](https://coder-studio.com/tutoriels/jamstack-explique/) — une architecture qui consomme abondamment des API. - [Node.js : le guide pour bien démarrer](https://coder-studio.com/tutoriels/node-js-guide/) — pour construire votre propre API côté serveur. - [Créer une application web : par où commencer en 2026](https://coder-studio.com/tutoriels/creer-application-web/) — replacer l’API dans un projet complet.