REST APIs

Qu’est-ce que REST ?

REST, ou Representational State Transfer, est un style architectural pour la conception d’API HTTP. Au lieu d’inventer des commandes, vous modélisez votre domaine sous forme de ressources et utilisez les méthodes déjà définies par HTTP pour interagir avec elles. Un POST /posts crée un article, GET /posts/42 en lit un, PATCH /posts/42 le met à jour et DELETE /posts/42 le supprime.

L’avantage principal est la familiarité. Chaque client HTTP, proxy, cache et outil comprend déjà les méthodes, les codes de statut et les headers. En suivant ces conventions, les clients peuvent prédire le comportement de votre API sans avoir à lire un manuel spécifique.

Ressources et URI

Les ressources sont les noms de votre API. Utilisez des collections au pluriel et identifiez les éléments individuels par leur id.

GET    /posts
POST   /posts
GET    /posts/42
PUT    /posts/42
PATCH  /posts/42
DELETE /posts/42

• Utilisez des noms, pas des verbes. La méthode fait office de verbe.
• Utilisez systématiquement des noms de collection au pluriel.
• Gardez les URL en minuscules avec des tirets, et non des underscores ou du camelCase.
• N’imbriquez que lorsque la relation est essentielle, comme /posts/42/comments.
• Ne placez pas le format dans le chemin ; utilisez le header Accept.

L’imbrication profonde devient vite problématique. /users/1/posts/2/comments/3 est difficile à construire et à documenter ; privilégiez /comments/3 et laissez les clients filtrer.

Méthodes et sémantique

Chaque méthode possède une sémantique définie sur laquelle s’appuient les clients et l’infrastructure.

Safe signifie que la méthode ne modifie pas l’état ; idempotent signifie que la répéter a le même effet que de l’exécuter une seule fois. Ne modifiez jamais de données avec GET, car les clients, les crawlers et les caches peuvent émettre des requêtes GET librement.

Codes d’état

Renvoyez le code correspondant à l’événement survenu. C’est l’élément sur lequel les clients s’appuient le plus.

• 200 OK — succès avec un corps de réponse.
• 201 Created — une ressource a été créée ; incluez un en-tête Location.
• 204 No Content — succès sans corps de réponse, courant pour DELETE.
• 400 Bad Request — requête malformée.
• 401 Unauthorized — authentification manquante ou invalide.
• 403 Forbidden — authentifié, mais accès non autorisé.
• 404 Not Found — ressource inexistante.
• 409 Conflict — conflit d’état, comme un doublon.
• 422 Unprocessable Entity — syntaxiquement valide, mais échoue à la validation.
• 429 Too Many Requests — limite de requêtes atteinte ; incluez Retry-After.
• 500 Internal Server Error — erreur serveur inattendue.

Renvoyer 200 avec { "success": false } masque les échecs pour les clients, les caches et le monitoring, et force chaque client à inventer sa propre gestion d’erreurs.

Collections : filtrage, tri et pagination

Les collections nécessitent un langage de requête cohérent.

GET /posts?status=published&sort=-createdAt&limit=20&cursor=abc123

• Filtrage avec field=value, et des clés répétées pour le OR.
• Tri avec sort=field ou sort=-field pour l’ordre décroissant.
• Pagination avec limit et cursor (ou page et perPage).
• Sélection de champs avec fields=id,title lorsque les clients souhaitent limiter les données.
• Recherche avec un paramètre q dédié.

Privilégiez la pagination par curseur pour les jeux de données volumineux ou évolutifs, et retournez toujours le curseur suivant dans la réponse afin que les clients puissent paginer sans deviner.

{
  "data": [{ "id": "42", "title": "Hello" }],
  "pagination": { "nextCursor": "abc123", "hasMore": true }
}

Représentations et réponses

Les réponses sont des représentations de ressources. Le JSON est la norme, avec une structure stable.

{
  "id": "42",
  "title": "Hello",
  "createdAt": "2026-09-15T10:00:00Z"
}

• Utilisez camelCase ou snake_case de manière cohérente, mais pas les deux.
• Utilisez des chaînes au format ISO 8601 pour les dates.
• Utilisez des identifiants stables sous forme de chaînes de caractères lorsque les clients risquent de dépasser la précision numérique.
• Enveloppez les collections avec data et pagination, mais retournez les ressources uniques directement.
• Supportez la Accept et définissez correctement le Content-Type.

Absence d’état (Statelessness) et mise en cache

Chaque requête doit contenir tous les éléments nécessaires à son traitement : l’URL, la méthode, les headers et le corps. Ne vous appuyez pas sur la mémoire du serveur entre deux requêtes ; c’est précisément ce qui vous permet de faire tourner plusieurs instances derrière un load balancer.

Comme la méthode GET est sûre et que les réponses sont autonomes, REST s’intègre parfaitement avec le cache HTTP. Configurez Cache-Control et des validateurs tels que ETag sur les ressources pouvant être mises en cache, comme détaillé dans le guide HTTP.

Erreurs

Utilisez un format d’erreur unique partout et documentez-le.

{
  "error": {
    "code": "validation_error",
    "message": "Title is required",
    "details": [{ "field": "title", "issue": "required" }]
  }
}

Un code lisible par la machine permet aux clients de gérer différents cas de figure, un message peut être affiché sans risque aux utilisateurs, et details aide les formulaires à mettre en évidence les champs concernés. Associez cela au code de statut approprié.

Bonnes pratiques

• Modélisez vos ressources avec des noms et laissez les méthodes exprimer les actions.
• Retournez le code de statut le plus spécifique possible.
• Versionnez l’API avant d’en avoir besoin et documentez-la (voir Versionnage d’API).
• Paginez chaque collection et limitez-la à limit.
• Validez les entrées et retournez des erreurs structurées.
• Utilisez une nomenclature et une casse cohérentes dans l’ensemble du projet.
• Mettez en cache les réponses GET sécurisées avec des headers explicites.
• Implémentez le rate limiting et l’authentification (voir Rate Limiting).

Erreurs courantes

• Utiliser des verbes dans les URLs qui font doublon avec les méthodes HTTP.
• Retourner un code 200 pour des erreurs.
• Proposer des collections non bornées sans pagination.
• Manquer de cohérence dans la casse, les formats de date ou la structure des erreurs.
• Créer des imbrications trop profondes, devenant impossibles à maintenir.
• Modifier l’état du serveur lors d’un GET.
• Casser les clients en modifiant silencieusement la structure des réponses.

Et après ?

REST est la méthode par défaut pour exposer un backend. Appuyez-vous sur le guide HTTP, documentez-le avec OpenAPI, faites-le évoluer en toute sécurité grâce au versionnage d’API et protégez-le avec le Rate Limiting. Comparez ce modèle avec GraphQL lorsque vos clients ont besoin de plus de flexibilité.