API RESTful : principes généraux

Une API RESTful est une API qui suit les principes de l'architecture REST[1] (Representational State Transfer).

Ces principes considèrent trois concepts clés :

  • les Ressources : ce sont les éléments essentiels d'une application, c'est-à-dire les données, les objets, les services, etc ;

  • les Collections : ce sont des groupes ou des listes de ressources ;

  • les URI[2] : des adresses uniques permettant d'accéder aux ressources et aux collections.

Exemple

Par exemple, pour une application web, on pourrait avoir :

  • une donnée nommée user, correspondant à un utilisateur, comme ressource ;

  • un ensemble d'utilisateurs, comme collection ;

  • les URI /user et /users permettant de localiser cette ressource et cette collection.

Les opérations standards d'une API REST sont parfois regroupées dans l'acronyme CRUD, qui fait référence aux verbes Create (Créer), Read (Lire), Update (Mettre à jour) et Delete (Supprimer). Les opérations CRUD sont directement associées aux méthodes HTTP.

Fondamental

Le principe fondamental de REST est d'utiliser les méthodes standardisées du protocole HTTP pour manipuler des ressources :

  • GET : pour récupérer une ressource ;

  • POST : pour créer une nouvelle ressource ;

  • PUT : pour mettre à jour une ressource existante ;

  • DELETE : pour supprimer une ressource.

Complément

D'autres méthodes du protocole HTTP peuvent être employées :

  • PATCH : pour appliquer une mise à jour partielle d'une ressource existante ;

  • HEAD : pour récupérer des informations sur une ressource, sans en récupérer les données (contrairement au GET) ;

  • OPTIONS : pour récupérer la liste des méthodes HTTP que supporte une ressource.

Dans une API, on définit des points de terminaison (endpoint[3]), pour interagir avec les ressources disponibles sur le serveur. Chaque endpoint correspond à une méthode standard HTTP pour spécifier l'action disponible pour la ressource liée à cet endpoint.

Exemple

Par exemple, on pourrait avoir les endpoints suivants :

  • GET /users : pour récupérer la liste de tous les utilisateurs ;

  • GET /users/{userId} : pour récupérer les détails de l'utilisateur spécifié par son ID ;

  • POST /users : pour créer un nouvel utilisateur ;

  • PUT /users/{userId} : pour mettre à jour les détails de l'utilisateur spécifié par son ID ;

  • DELETE /users/{userId} : pour supprimer l'utilisateur spécifié par son ID.