Créer une API REST : les bases

Dans le guide des API, tu étais le client du restaurant : carte, commande, plat. Aujourd’hui, tu passes le comptoir — tablier fourni. Créer une API REST est LE projet fondateur du back-end : ce guide t’en donne les conventions, le pas-à-pas avec Express, et les bonnes pratiques — la suite directe de Node.js expliqué, dans le grand parcours apprendre à coder.

REST : les conventions du passe-plat

REST n’est ni un langage ni un outil : c’est un style d’architecture — un ensemble de conventions qui rendent une API prévisible pour quiconque la découvre. Convention 1 : tout est ressource, désignée par une URL stable — la collection au pluriel (/livres), l’élément par son identifiant (/livres/12). Convention 2 : l’action se dit par le verbe — non dans l’URL (/supprimerLivre12 est un péché), mais par la méthode HTTP de la requête : GET lit, POST crée, PUT (ou PATCH) modifie, DELETE supprime. La grille croisée verbe × URL décrit tout : GET /livres = la liste ; GET /livres/12 = le livre 12 ; POST /livres = créer un livre ; DELETE /livres/12 — tu lis couramment.

Convention 3 : les réponses voyagent en JSON — le bordereau standardisé — accompagnées d’un code de statut honnête : 200 pour la lecture réussie, 201 pour la création (« créé »), 404 pour la ressource introuvable, 400 pour la demande mal formée. Ces conventions ne sont pas de la coquetterie : elles sont le contrat qui permet à un front-end, une app mobile ou un autre serveur de consommer ta cuisine sans lire ton code — la carte du restaurant, écrite dans la grammaire que tout le métier partage. Le jeu complet des quatre opérations sur une ressource porte un nom que tu croiseras partout : le CRUD — Create, Read, Update, Delete — l’alphabet du back-end.

Ton API pas à pas, en mots

L’atelier, maintenant — une soirée, promis. Étape 1 : le squelette. Un dossier, npm init pour le fichier d’identité, npm install express pour la charpente — le framework minimaliste et standard du serveur Node. Le fichier de départ tient en quatre idées lues en mots : « importe Express ; crée l’application ; dis-lui de comprendre le JSON entrant ; écoute le port 3000 ». Lance node serveur.js : ta cuisine est ouverte, en local. Étape 2 : la ressource en mémoire. Avant toute base de données, un simple tableau JavaScript de livres — trois objets avec id, titre, auteur — fait la réserve : l’astuce pédagogique qui isole ce qu’on apprend (les routes) de ce qu’on apprendra ensuite (la persistance).

Étape 3 : les routes, une par une — chacune se lit comme une phrase. « Quand arrive GET /livres → renvoie le tableau en JSON. » « Quand arrive GET /livres/:id → cherche le livre ; trouvé, renvoie-le ; sinon, réponds 404 avec un petit JSON d’erreur » — ta première condition de cuisine. « Quand arrive POST /livres → lis le corps de la requête, fabrique le livre avec un nouvel id, ajoute-le au tableau, réponds 201 avec le livre créé. » Puis PUT et DELETE sur le même modèle — et le CRUD est complet. Étape 4 : tester. Le navigateur suffit pour les GET ; pour POST, PUT et DELETE, un outil de requêtes s’impose — les clients d’API graphiques ou la commande curl — et chaque test vérifie le trio : le bon verbe, la bonne réponse, le bon code. À ce stade, prends dix secondes pour savourer : un vrai client — le fetch de tes pages, une app — peut consommer ta cuisine. Le passe-plat fonctionne dans les deux sens, et tu es des deux côtés.

Les bonnes pratiques de départ (et la suite)

Cinq habitudes, prises maintenant, te classent d’emblée. Les noms au pluriel et sans verbes : /livres, /utilisateurs — l’action vit dans le verbe HTTP, jamais dans l’URL. Les codes justes : 201 à la création, 404 à l’introuvable, 400 à la demande invalide — le client d’API lit les codes avant les corps, honore ce réflexe. Les erreurs en JSON : jamais de silence ni de page HTML d’erreur — toujours un petit bordereau { « erreur »: « livre introuvable » }, cousin direct du plan B des exceptions : ton try/catch de cuisine se termine par une réponse digne. La validation des entrées : un POST sans titre mérite un 400 explicatif — ne jamais faire confiance au client, règle d’or gravée dès le premier jour. La cohérence, enfin : mêmes formats, mêmes conventions sur toutes les routes — une API prévisible est une API aimée.

Et la suite du voyage, dans l’ordre naturel : remplacer le tableau en mémoire par une vraie base de données — SQLite pour commencer, les routes ne changent presque pas, c’est toute la beauté de la séparation ; puis brancher un vrai front dessus — ta liste de tâches React ou Vue consommant TON API : le moment où la salle et la cuisine que tu as construites se parlent — le projet full-stack complet, celui des portfolios qui convainquent. L’authentification, les autorisations et le déploiement viendront à leur heure ; ce soir, ta première carte est imprimée, et elle est dans les règles de l’art.

Questions fréquentes

C’est quoi une API REST, en une phrase ?

Une API qui suit les conventions du web : chaque ressource a son URL (/livres, /livres/12), l’action se dit par le verbe HTTP (GET lire, POST créer, PUT modifier, DELETE supprimer), et les réponses voyagent en JSON avec un code de statut honnête. Ces règles rendent l’API prévisible pour tout client.

Que signifie CRUD ?

Create, Read, Update, Delete — créer, lire, modifier, supprimer : les quatre opérations fondamentales sur une ressource, qui correspondent aux verbes POST, GET, PUT/PATCH et DELETE d’une API REST. Implémenter le CRUD complet sur une ressource est le rite de passage classique du back-end.

Pourquoi commencer avec des données en mémoire plutôt qu’une base ?

Pour isoler l’apprentissage : un simple tableau d’objets fait office de réserve et laisse toute l’attention aux routes, verbes et codes de statut. La base de données (SQLite d’abord) se branche ensuite sans presque toucher aux routes — c’est la preuve que la séparation des rôles fonctionne.

Comment tester une API REST pendant le développement ?

Le navigateur suffit pour les requêtes GET ; pour POST, PUT et DELETE, utilise un client d’API graphique ou la commande curl : tu choisis le verbe, l’URL et le corps JSON, et tu vérifies le trio réponse-code-format. Tester chaque route au fil de l’écriture évite les surprises en cascade.

Sources

• MDN Web Docs — HTTP, verbes, codes de statut et JSON en référence
• Node.js — la plateforme officielle de ton serveur

Cet article a une vocation informative et pédagogique. Les plateformes, outils et formations éventuellement cités le sont à titre d’exemple ; compare plusieurs options avant de t’engager ou de payer.