Comprendre REST

REST signifie Representational State Transfer. C’est un style d’architecture pour concevoir des services web. Une API REST expose des ressources accessibles par des URLs, puis utilise les méthodes HTTP pour lire, créer, modifier ou supprimer ces ressources.

Une ressource peut être un utilisateur, un article, une commande, un commentaire, un produit ou tout autre élément métier manipulé par une application.

REST n’est pas un framework, ni un langage, ni une librairie. C’est une manière d’organiser les échanges entre un client et un serveur en respectant des conventions simples, prévisibles et compréhensibles.

Pour comprendre REST, il faut distinguer trois notions : la ressource, son URL et sa représentation.

Une même ressource peut avoir plusieurs représentations. Par exemple, un utilisateur peut être affiché sous forme de page HTML dans un navigateur, ou retourné sous forme de JSON dans une API.

{
  "id": 42,
  "name": "Alice Martin",
  "email": "alice@example.com"
}

REST repose sur plusieurs contraintes d’architecture. Elles permettent de créer des APIs compréhensibles, évolutives et faciles à consommer.

Deux notions sont très utiles pour comprendre les méthodes HTTP : les méthodes sûres et les méthodes idempotentes.

Une API REST ne doit pas retourner 200 OK pour toutes les situations. Le code HTTP aide le client à comprendre le résultat réel de la requête.

Une URL RESTful doit identifier une ressource de manière claire, stable et prévisible. Elle doit privilégier les noms de ressources plutôt que les verbes d’action.

GET    /users
POST   /users
GET    /users/42
PUT    /users/42
PATCH  /users/42
DELETE /users/42

REST ne limite pas les réponses à JSON. Une ressource peut être représentée en HTML, XML, JSON ou dans un autre format. En pratique, les APIs web modernes utilisent très souvent JSON, car il est simple à lire et facile à manipuler en JavaScript.

Une bonne représentation doit être claire, prévisible et cohérente. Les noms de champs doivent être stables, les relations doivent être compréhensibles, et les erreurs doivent avoir un format régulier.

{
  "id": 42,
  "title": "Découvrir REST",
  "content": "Une ressource est retournée sous forme de représentation JSON.",
  "author": {
    "id": 7,
    "href": "/users/7"
  }
}

Lorsqu’une API retourne une erreur, le format devrait également rester cohérent. Le client peut alors traiter les erreurs plus facilement.

Le modèle de Richardson permet d’évaluer progressivement la maturité REST d’une API. Il ne remplace pas les contraintes REST, mais il donne une grille de lecture très utile pour comprendre les étapes d’amélioration d’une API HTTP.

POST /api
{
  "action": "getUser",
  "id": 42
}

POST /users/42
POST /orders/15

GET    /users/42
PUT    /users/42
DELETE /users/42

{
  "id": 42,
  "name": "Alice",
  "_links": {
    "self": { "href": "/users/42" },
    "orders": { "href": "/users/42/orders" }
  }
}

Une API REST doit aussi être claire lorsqu’une requête échoue. Le code HTTP indique la catégorie de problème, mais le corps de réponse peut fournir un message plus précis.

{
  "code": 404,
  "message": "Ressource introuvable"
}

L’important est de garder un format stable. Le client peut ainsi afficher un message, déclencher une redirection, demander une nouvelle authentification ou corriger les données envoyées.