API REST — Le guide complet

D'où ça vient ?

REST (Representational State Transfer) est un style architectural décrit par Roy Fielding en 2000, dans sa thèse sur les architectures logicielles pour le web. Ce n'est ni un protocole ni une norme figée : c'est un ensemble de contraintes que doit respecter une API pour être qualifiée de RESTful. En pratique, la grande majorité des API dites "REST" n'appliquent qu'une partie de ces contraintes — mais le vocabulaire et les conventions (verbes HTTP, ressources via URL) sont devenus le standard de facto des API web.

Le principe : des ressources, pas des actions

Une API REST expose des ressources (un utilisateur, une commande, un article) identifiées par une URL, et on agit dessus via les verbes HTTP plutôt que via le nom de l'action dans l'URL elle-même.

Verbe HTTP	Action CRUD	Exemple
`GET`	Read	`GET /utilisateurs/1` — récupère l'utilisateur n°1
`POST`	Create	`POST /utilisateurs` — crée un nouvel utilisateur
`PUT`	Update (remplacement complet)	`PUT /utilisateurs/1` — remplace l'utilisateur n°1
`PATCH`	Update (partiel)	`PATCH /utilisateurs/1` — modifie un ou plusieurs champs
`DELETE`	Delete	`DELETE /utilisateurs/1` — supprime l'utilisateur n°1

L'URL désigne la ressource (/utilisateurs/1), jamais l'action (/getUtilisateur?id=1 n'est pas RESTful).

Cycle d'une requête

sequenceDiagram
    participant C as Client
    participant S as Serveur
    C->>S: GET /utilisateurs/1
    S-->>C: 200 OK { "id": 1, "nom": "..." }
    C->>S: PATCH /utilisateurs/1 { "nom": "Nouveau nom" }
    S-->>C: 200 OK { "id": 1, "nom": "Nouveau nom" }
    C->>S: DELETE /utilisateurs/1
    S-->>C: 204 No Content

Stateless : la contrainte la plus structurante

Une API REST ne conserve aucun état de session entre deux requêtes. Chaque appel doit contenir tout ce qui est nécessaire à son traitement (authentification via token, paramètres, etc.). Conséquence directe : n'importe quel serveur du parc peut traiter n'importe quelle requête, ce qui simplifie énormément le scaling horizontal et le load balancing.

API vs API REST

Une API est un concept générique : n'importe quelle interface permettant à deux programmes de communiquer (bibliothèque, RPC, SOAP...). REST est un style architectural précis parmi d'autres façons de construire une API — celui qui s'est imposé pour le web grâce à sa simplicité et son appui sur HTTP, un protocole déjà universellement supporté.

REST vs GraphQL vs gRPC

REST — expose des ressources fixes par endpoint ; simple à mettre en cache (HTTP), mais peut sur- ou sous-récupérer des données (un endpoint renvoie souvent plus, ou moins, que ce dont le client a besoin).
GraphQL — un point d'entrée unique où le client décrit précisément les champs qu'il veut récupérer. Résout le problème d'over/under-fetching, au prix d'une complexité de mise en cache plus élevée.
gRPC — utilise HTTP/2 et un format binaire (Protocol Buffers) plutôt que JSON. Très performant, mais peu adapté aux clients navigateurs ; privilégié pour la communication interne entre microservices.

Bonnes pratiques

Ressources au pluriel — /utilisateurs plutôt que /utilisateur, pour rester cohérent que la requête cible la collection ou un élément.
Codes de statut HTTP corrects — 200 (OK), 201 (créé), 204 (pas de contenu), 400 (requête invalide), 404 (introuvable), 401/403 (authentification/autorisation).
Versioning explicite — /api/v1/utilisateurs, pour faire évoluer l'API sans casser les clients existants.
Pagination — indispensable dès qu'une collection peut grossir (?page=2&limit=50), pour éviter de renvoyer des milliers d'éléments d'un coup.
Documentation générée — décrire l'API avec OpenAPI/Swagger plutôt qu'à la main, pour qu'elle reste synchronisée avec le code.

Une vidéo complémentaire

Vidéo de Cookie Connecté - va donner de la force.