API REST : principes et bonnes pratiques

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.