Concevoir une API REST

Une API (Application Programming Interface) est une interface qui permet à deux programmes de dialoguer. Sur le web, une API expose des fonctionnalités et des données qu'un client (une application mobile, un site React, un autre serveur) peut consommer à distance. Quand ton application React va chercher la liste des articles auprès d'un serveur, elle appelle une API. C'est le pont entre le frontend et le backend, et entre les services entre eux.

REST (Representational State Transfer) n'est pas une technologie mais un style d'architecture : un ensemble de conventions pour concevoir des API web cohérentes et prévisibles. Une API qui respecte ces conventions est dite « RESTful ». L'immense majorité des API web que tu croiseras sont REST : c'est le standard de fait. En maîtriser les principes, c'est savoir concevoir et consommer la plupart des API du marché.

Les principes clés de REST

• Tout est ressource : on manipule des « choses » (des articles, des utilisateurs), chacune identifiée par une URL.
• Client-serveur : le client et le serveur sont indépendants et communiquent via des requêtes.
• Sans état (stateless) : chaque requête est autonome, le serveur ne « se souvient » pas de la précédente.
• S'appuie sur HTTP : les méthodes (GET, POST...) et les codes de statut du web portent le sens.

Le principe sans état mérite une explication : chaque requête envoyée au serveur doit contenir toutes les informations nécessaires pour être traitée (par exemple, le jeton d'authentification). Le serveur ne conserve pas le contexte entre deux requêtes. Cette contrainte, un peu abstraite, rend les API plus simples à mettre à l'échelle : n'importe quel serveur peut traiter n'importe quelle requête, sans mémoire partagée.

Le cœur de la conception REST est de raisonner en ressources : des entités que l'API expose (des articles, des utilisateurs, des commandes). Chaque ressource, et chaque collection de ressources, possède sa propre URL. La règle fondatrice, contre-intuitive au début : l'URL nomme une chose, pas une action. Le quoi (la ressource) est dans l'URL ; le comment (l'action) est porté par la méthode HTTP, qu'on verra au chapitre suivant.

# ✅ Bien : l'URL nomme une ressource (un nom, au pluriel)
GET    /articles
GET    /articles/42
POST   /articles

# ❌ À éviter : un verbe dans l'URL (l'action est déjà dans la méthode)
GET    /getArticles
POST   /createArticle
GET    /articles/42/delete

Remarque la différence. La bonne version utilise un nom au pluriel (/articles) pour la collection, et l'identifiant pour une ressource précise (/articles/42). La mauvaise version met des verbes dans l'URL (getArticles, createArticle) : c'est redondant, puisque la méthode HTTP exprime déjà l'action. Une URL RESTful se lit comme un chemin vers une chose, jamais comme une commande.

Exprimer les relations

GET  /articles/42/commentaires      # les commentaires de l'article 42
GET  /utilisateurs/7/commandes      # les commandes de l'utilisateur 7
POST /articles/42/commentaires      # ajouter un commentaire à l'article 42

Quand une ressource en contient d'autres, on l'exprime par la hiérarchie de l'URL : /articles/42/commentaires désigne les commentaires appartenant à l'article 42. Cette imbrication rend les relations lisibles au premier coup d'œil. On évite toutefois d'imbriquer trop profondément (au-delà de deux niveaux, ça devient illisible) : il vaut mieux repartir de la ressource racine.

Puisque l'URL nomme la ressource, c'est la méthode HTTP qui exprime ce qu'on veut en faire. Les quatre opérations de base, le CRUD, s'associent chacune à une méthode. C'est cette grammaire, une URL + une méthode, qui structure toute API REST.

GET    /articles       # Read   : lire la liste des articles
GET    /articles/42    # Read   : lire l'article 42
POST   /articles       # Create : créer un nouvel article
PUT    /articles/42    # Update : remplacer entièrement l'article 42
PATCH  /articles/42    # Update : modifier partiellement l'article 42
DELETE /articles/42    # Delete : supprimer l'article 42

GET lit, POST crée, DELETE supprime. Pour la modification, deux méthodes existent : PUT remplace entièrement la ressource (tu envoies l'objet complet), tandis que PATCH modifie seulement certains champs (tu n'envoies que ce qui change). En pratique, PATCH est souvent plus pratique pour une mise à jour partielle, comme cocher une tâche comme faite.

Deux propriétés à connaître : sûr et idempotent

• Sûre (safe) : la méthode ne modifie rien côté serveur. GET est sûre : la consulter cent fois ne change rien.
• Idempotente : l'appeler plusieurs fois produit le même résultat qu'une seule. PUT et DELETE le sont ; POST ne l'est pas (deux POST créent deux ressources).

Ces propriétés ne sont pas de la théorie gratuite : elles ont des conséquences concrètes. Un GET ne doit jamais modifier de données (mettre une suppression derrière un GET est une faute grave : un simple préchargement de lien pourrait tout effacer). L'idempotence permet de réessayer sans danger une requête en cas de coupure réseau : rejouer un DELETE déjà passé ne casse rien, alors que rejouer un POST créerait un doublon. Un jury apprécie que tu saches expliquer ces nuances.

À chaque requête, le serveur répond avec un code de statut HTTP : un nombre à trois chiffres qui résume le résultat. Le premier chiffre donne la grande catégorie, et c'est déjà l'essentiel à retenir.

• 2xx — Succès : la requête a réussi (200 OK, 201 Created, 204 No Content).
• 3xx — Redirection : la ressource est ailleurs (301 déplacée définitivement, 304 non modifiée).
• 4xx — Erreur du client : la requête est fautive (400 invalide, 401 non authentifié, 403 interdit, 404 introuvable).
• 5xx — Erreur du serveur : le serveur a échoué (500 erreur interne, 503 service indisponible).

La distinction clé : 4xx, c'est la faute du client (il a mal formulé sa requête, oublié de s'authentifier, demandé une ressource inexistante) ; 5xx, c'est la faute du serveur (un bug, une panne). Renvoyer le bon code n'est pas cosmétique : le client s'appuie dessus pour réagir. Un 404 lui dit « cette ressource n'existe pas », un 401 « connecte-toi d'abord », un 400 « corrige ta requête ».

Les codes à maîtriser pour une API CRUD

GET    /articles/42   ->  200 OK           (trouvé, voici les données)
GET    /articles/999  ->  404 Not Found    (cet article n'existe pas)
POST   /articles      ->  201 Created      (créé avec succès)
POST   /articles      ->  400 Bad Request  (données invalides)
DELETE /articles/42   ->  204 No Content   (supprimé, rien à renvoyer)
(sans jeton valide)   ->  401 Unauthorized (authentification requise)

Ces quelques codes couvrent l'essentiel d'une API CRUD. Note les subtilités : 201 (et non 200) pour signaler une création, 204 pour un succès sans contenu à renvoyer (typique d'une suppression), 401 quand l'authentification manque, 403 quand on est authentifié mais pas autorisé. Cette précision distingue une API amateur d'une API soignée.

Client et serveur doivent parler la même langue pour échanger des données. Sur le web, ce langage est le JSON (JavaScript Object Notation) : un format texte, léger, lisible par les humains comme par les machines, universellement supporté. Une API REST reçoit et renvoie du JSON dans le corps (body) des requêtes et des réponses.

{
  "id": 42,
  "titre": "Bien concevoir une API REST",
  "auteur": "Alice",
  "publie": true,
  "tags": ["api", "rest", "backend"],
  "dateCreation": "2026-07-15"
}

Un objet JSON associe des clés à des valeurs (texte, nombre, booléen, tableau, objet imbriqué). Une bonne API structure ses réponses de façon cohérente : mêmes noms de champs partout, même façon de représenter les dates (le format ISO 8601, comme 2026-07-15, est le standard), mêmes conventions de casse. Un client qui connaît un objet article doit le retrouver identique partout dans l'API.

Les en-têtes Content-Type et Accept

# Le client envoie du JSON et déclare ce qu'il envoie
POST /articles
Content-Type: application/json

{ "titre": "Nouvel article" }

# Le client peut préciser ce qu'il souhaite recevoir
GET /articles
Accept: application/json

Deux en-têtes (headers) encadrent l'échange. Content-Type: application/json déclare le format des données envoyées dans le corps : sans lui, le serveur ne sait pas comment interpréter ce qu'il reçoit (souviens-toi du middleware express.json() du cours Node). Accept, à l'inverse, indique le format que le client souhaite en retour. Ces en-têtes font partie du contrat, même s'ils sont souvent gérés automatiquement par les outils.

Que se passe-t-il si GET /articles doit renvoyer un million d'articles ? La requête serait énorme, lente, inutilisable. Une API bien conçue permet au client d'affiner ce qu'il demande grâce aux paramètres de requête (la query string, ce qui suit le ? dans l'URL). Trois besoins reviennent toujours : filtrer, trier, paginer.

# Filtrer : ne garder que ce qui correspond
GET /articles?auteur=alice&publie=true

# Trier : ordonner les résultats
GET /articles?tri=date&ordre=desc

# Paginer : découper en pages de résultats
GET /articles?page=2&limite=20

Ces paramètres se combinent librement : /articles?auteur=alice&tri=date&page=2 demande la deuxième page des articles d'Alice, triés par date. Le filtrage réduit l'ensemble selon des critères, le tri l'ordonne, la pagination le découpe en tranches consultables. Contrairement aux ressources (dans le chemin), ces options vont bien dans la query string : ce sont des modulations d'une même collection, pas des ressources différentes.

La pagination, en pratique

{
  "donnees": [
    { "id": 21, "titre": "..." },
    { "id": 22, "titre": "..." }
  ],
  "pagination": {
    "page": 2,
    "limite": 20,
    "total": 137
  }
}

Une réponse paginée ne contient pas que les données : elle inclut des métadonnées qui disent au client où il en est (page actuelle, taille de page, nombre total de résultats). Sans ces informations, le client ne peut pas construire une navigation « page suivante / précédente » ni savoir combien de pages existent. Fournir ces métadonnées est ce qui rend la pagination réellement exploitable.

Une API est une porte ouverte sur tes données : elle doit être protégée. Deux notions à distinguer clairement. L'authentification répond à « qui es-tu ? » (prouver son identité). L'autorisation répond à « as-tu le droit de faire ça ? » (les permissions). Une requête peut être authentifiée (on sait qui c'est) mais non autorisée (cette personne n'a pas le droit), d'où la distinction entre les codes 401 et 403.

L'authentification par jeton

# Le client envoie un jeton dans l'en-tête Authorization
GET /mon-compte
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

# Sans jeton valide, le serveur refuse :
GET /mon-compte   ->  401 Unauthorized

La méthode la plus répandue est l'authentification par jeton (token). Après connexion, le serveur remet au client un jeton (souvent un JWT), que le client renvoie à chaque requête dans l'en-tête Authorization. Comme REST est sans état, ce jeton doit accompagner chaque requête : le serveur ne se souvient pas que tu étais connecté à la requête précédente. Le serveur vérifie le jeton et sait alors qui appelle.

Les réflexes de sécurité indispensables

• HTTPS partout : chiffre les échanges, y compris les jetons. Non négociable.
• Valider toutes les entrées : ne jamais faire confiance aux données du client (types, formats, longueurs).
• Limiter le débit (rate limiting) : plafonner le nombre de requêtes pour contrer les abus et les attaques.
• Ne pas fuiter d'informations : les messages d'erreur ne révèlent ni détail technique, ni structure interne.
• Gérer le CORS : contrôler quels sites du navigateur ont le droit d'appeler l'API.

Une API est faite pour être consommée par d'autres : ton frontend, une équipe voisine, des clients externes. Sa qualité se mesure à la facilité avec laquelle on la comprend et on l'utilise. Deux ingrédients y contribuent avant tout : la cohérence de la conception, et une bonne documentation. Une API brillante mais indocumentée reste inutilisable.

Le récapitulatif des bonnes pratiques

• Des URL de ressources : noms au pluriel, pas de verbes, hiérarchie pour les relations.
• La bonne méthode HTTP : GET pour lire, POST créer, PUT/PATCH modifier, DELETE supprimer.
• Le bon code de statut : 2xx succès, 4xx faute du client, 5xx faute du serveur.
• Un JSON cohérent : mêmes champs, mêmes formats de date, mêmes conventions partout.
• Des erreurs structurées : un code de statut juste et un message JSON explicite.
• Le versionnement pour évoluer sans casser les clients existants.

Documenter avec OpenAPI

Le standard de documentation d'API s'appelle OpenAPI (anciennement Swagger). Il décrit ton API dans un fichier structuré : les URL disponibles, les méthodes, les paramètres attendus, les formats de réponse, les codes de statut. À partir de ce fichier, des outils génèrent une documentation interactive (comme Swagger UI) où l'on peut lire l'API et tester les requêtes directement depuis le navigateur. C'est le standard attendu dans l'industrie.

Une bonne documentation indique, pour chaque point d'entrée : ce qu'il fait, les paramètres et leur type, un exemple de requête, un exemple de réponse, et les codes d'erreur possibles. Le meilleur test d'une API : une développeuse qui ne t'a jamais parlé peut-elle l'utiliser en lisant uniquement la doc ? Si oui, tu as réussi.