REST, pour REpresentational State Transfer, est un type architectural définissant un ensemble de contraintes à mettre en place sur des services web. Se basant sur le protocole HTTP, ce style d’architecture est aujourd’hui devenu une norme dans le monde du développement back-end.
Vous voulez en savoir plus sur les API REST ? Comprendre comment fonctionne cette architecture ? Apprendre à construire ces API ? Suivez le guide !
Le point sur les API
Pour parler architecture REST, il faut déjà connaitre les bases : commençons par expliquer ce qu’est une API.
Une API, ou interface de programmation, est, dans le cas d’un service web, un point d’entrée vers le serveur. Une API répond à un besoin très spécifique (récupérer une liste, modifier une entrée de base de données, etc.) et est accessible via une URL.
L’API peut être publique et accessible à tout développeur (par exemple : API de météo, gouvernementales), ou privées (nécessitant une authentification et non accessible de l’extérieur).
API RESTful : la définition
Maintenant que nous savons ce qu’est une API, parlons du thème principal de cet article : les API REST.
Nous l’avons dit, REST est un ensemble de normes qui structurent des API. On parle aussi d’API RESTful.
Historiquement, le terme REST a été défini par l’informaticien américain Roy Fielding, en 2000. Roy Fielding est notamment connu pour être l’un des principaux auteurs de la spécification HTTP, et a aidé au développement des premiers serveurs web.
C’est donc lors de cette année qu’ont été définies, basés sur le protocole HTTP 1.0, les règles qui distinguent une API d’une API REST. Ces règles sont au nombre de 6 ; voyons-les en détails.
Les 6 contraintes définissant une architecture RESTful
1) La séparation client-serveur
La première contrainte qui définit une architecture REST, est le respect du protocole client-serveur. Le protocole client-serveur, c’est tout simplement la séparation du client (généralement le navigateur web) du serveur distant.
Cette séparation permet une évolution indépendante des deux parties, tout en s’assurant de la compatibilité des différentes versions.
2) L’utilisation du stateless
La deuxième contrainte imposée par REST est le respect du stateless (ou sans état, en français).
Cela signifique que l’API ne doit garder aucune trace (ou état) des précédentes requêtes. Chaque point d’entrée doit être indépendant et appelable sans condition préalable.
C’est le client (le front-end) qui doit garder les informations utiles et envoyer dans la requête tout ce qui va permettre au serveur de générer la réponse attendue.
3) Avec de la mise en cache
Une API REST doit permettre la mise en place de cache réseau. C’est-à-dire que les réponses aux appels serveur doivent dire si, oui ou non, l’API appelée est cachable. L’utilisation de cache est recommandée pour de nombreuses raisons :
- Un chargement plus rapide (puisque pas ou moins d’utilisation serveur) ;
- Des coûts de serveur optimisés (surtout si on fait du serverless) ;
- Une moindre consommation des ressources (du web plus « écologique »).
Toutefois, attention à bien définir la différence entre une donnée toujours valide et une donnée périmée lors de la mise en place du cache.
4) Une interface uniforme
L’API doit être définie de manière uniforme, peu importe d’où vient l’appel, et toutes les API doivent respecter cette uniformité.
Cela permet, notamment, de pouvoir connecter plusieurs ressources (ou consommateurs de données) aux mêmes interfaces sans qu’il y ait de problèmes de communication, tout en permettant une compréhension plus facile (de la part des développeurs).
5) Un système en couches
Le développement d’un système sous forme de couches permet d’éviter une dépendance entre différents éléments (API, méthodes, etc.).
Concrètement, le client peut appeler une ressource particulière, et celle-ci peut appeler elle-même d’autres ressources, sans qu’elles soient directement liées.
Cela veut aussi dire que le front ne sait jamais sur quelle couche il fait ses appels.
6) Du code à la demande (facultatif)
REST doit aussi permettre la possibilité au client de télécharger du code, qu’il exécutera directement. C’est facultatif, et assez peu utilisé, notamment car tous les clients ne sont pas capables d’exécuter le même code.
Les différents verbes REST
Les API RESTful utilisent donc le protocole HTTP pour gérer les requêtes et resources web. Cela veut dire qu’elles doivent utiliser les verbes (ou méthodes) HTTP définis pour créer les API.
Voici la liste des principales méthodes, et leurs utilisations normées :
| URI (exemple) | GET | POST | PUT | DELETE | PATCH |
| http://api.exemple.com/users/42 | Récupère les données de l’utilisateur d’identifiant 42 | Crée un utilisateur avec l’identifiant 42 | Modifie entièrement l’utilisateur d’identifiant 42 avec de nouvelles données | Supprime l’utilisateur d’identifiant 42 | Modifie partiellement l’utilisateur 42 avec les informations envoyées (modification ciblée) |
Ce sont les verbes qu’on retrouve la plupart du temps sur des back-end utilisant REST. Cependant, il en existe d’autres, beaucoup moins utilisés, voire peu ou pas connus :
- HEAD : Fais la même requête que le GET, mais sans renvoyer le body de la réponse (seulement l’en-tête) ;
- CONNECT : ce verbe établit un tunnel vers la ressource ciblée ;
- OPTIONS : cette méthode est utilisée pour décrire les options de communications avec l’API cible ;
- TRACE : Réalise un message de test vers la ressource (API) ciblée.
Pour plus de détails concernant les verbes et méthodes HTTP, nous vous invitons à aller voir cette documentation.
Les concurrents de REST
REST étant plus une norme qu’une technologie, on ne peut pas vraiment parler de concurrence. Néanmoins, il existe des alternatives aux API RESTful. C’est notamment le cas de GraphQL.
Si avec REST c’est le serveur qui a la main sur les données retournées, GraphQL a opté pour la logique inverse. En effet, sa principale particularité, c’est d’envoyer dans la requête (uniquement du POST) la structure de données qu’on veut récupérer dans la réponse.
Par exemple, pour récupérer un objet JSON ressemblant à cela :
Le front-end, lors de la requête, pourrait envoyer un objet ressemblant à :
Si vous voulez en savoir plus sur GraphQL, nous avons écrit un article complet à ce sujet, à retrouver ici !
Les API REST par l’exemple
Différentes technos RESTFul
Le développement d’API RESTful vous intéresse, et vous voulez savoir comment faire ? Il convient dans un premier temps de choisir quelle techno vous allez utiliser.
Cela dépend évidemment de vos connaissances actuelles (langage, framework, etc.) et des technos vers lesquelles vous voulez vous diriger.
Mais il est possible de faire des API REST avec beaucoup de technos et de frameworks différents, par exemple :
- En JavaScript, avec Node.js (et Express) ;
- En Python, avec Django ou Flask, par exemple ;
- Ou avec Ruby et Ruby on Rails.
Il est même possible de créer des API REST avec du serverless, comme avec Amazon Web Services ou Google Cloud Platform.
Exemple avec Node.js
Pour que tout cela soit plus clair, voyons un cas concret d’API REST avec Node.js et Express. Nous allons prendre l’exemple d’un back-end chargé de récupérer, créer et supprimer des utilisateurs d’une web app.
Nous allons mettre toute la partie définition de modèles et création de base de données de côté pour simplifier l’exemple.
Commençons déjà par la création du serveur express :
const express = require('express');
const app = express();
const port = 3000;
var server = app.listen(port, () => {
console.log(`Example app listening on port ${port}`)
});La récupération d’un utilisateur d’identifiant id via un GET ressemblerait à :
app.get('/user/:id', function (req, res) {
// DO STUFF TO GET AND RETURN USER
})La création d’un utilisateur, via une requête POST, pourrait être définie comme :
app.post('/user', function (req, res) {
// GET DATA FROM 'req' AND CREATE USER
})Alors que la requête de suppression, via un DELETE, serait plutôt :
app.delete('/user/:id', function (req, res) {
// DELETE USER WITH GIVEN ID
})Bien sûr, nous n’avons ici que la définition des routes des API. Tout le reste, le code métier, est dépendant des normes de codage internes et des choix technologiques (base de données, modules npm, etc.)
Aller plus loin avec les API
Pour conclure cet article, parlons un peu de ce qu’il est possible de faire avec des API développées.
Car, en effet, en dehors d’API privées créées pour un projet spécifique, il est possible d’écrire des interfaces de programmation publique pouvant intéresser d’autres personnes (entreprises ou développeurs) et… de les monétiser !
Il est aujourd’hui simple de créer des API et de gagner de l’argent grâce à elles, notamment via des marketplaces. Si vous voulez en savoir plus, nous avons sur notre blog un article qui explique comment faire !
Et vous, avez-vous déjà eu à développer des API REST ? Qu’est-ce que vous en avez pensé ? Quelle est votre techno REST préférée ? Dites-nous tout en commentaire !
