Qu’est-ce qu’une API REST ?

Table des matières

• Introduction
• Les contraintes d’une API RESTful
• L’architecture Client-Serveur
• L’absence d’état
• La mise en cache
• Le système par couche
• Le code à la demande
• L’interface standardisée
• Les méthodes HTTP

Aujourd’hui, les API REST font partie intégrante du développement d’application Web et deviennent une des solutions techniques les plus viables pour connecter des services entre eux.

REST et API sont les acronymes de Representational State Transfer et d’Application Programming Interface. Commençons par comprendre ce que ces noms signifient réellement.

Introduction

D’après MDN, REST est une liste de contraintes à respecter dans la conception d’une API, pour obtenir un système efficace, fiable, évolutif. Ce n’est donc pas une technologie a proprement parler mais plutôt une manière d’organiser des données. On parlera alors d’architecture de données ou de méthode de conception pour obtenir des réponses prévisibles et cohérentes. Ces réponses, aussi appelées ressources dans certains cas, sont la plupart du temps au format JSON, qui fournit une représentation des données structurées et standardisée.

Concrètement une réponse au format JSON ressemble à ça :

{"menu": {
  "id": "primary-menu",
  "value": "Menu principal",
  "menuitem": [
    {"anchor": "Accueil", "url": "https://learn.fantassin.fr"},
    {"anchor": "Base de connaissance", "url": "https://learn.fantassin.fr/apprendre-wordpress/"},
    {"anchor": "Formations", "url": "https://learn.fantassin.fr/formations/"}
  ]
}}

À titre d’exemple, quand on visite un site sur un ordinateur de bureau ou sur un smartphone, on utilise deux applications Web différentes pour accéder aux mêmes données à partir de la même ressource REST.

Tout ce va et vient est contrôlée par une API, une interface de programmation. Une API est un ensemble de règles qui existent à l’intérieur d’une application Web, qui permettent une interaction entre cette application et d’autres services, d’autres logiciels ou du matériel.

Les 6 contraintes d’une API RESTful

On dit d’une API qu’elle est RESTful lorsqu’elle respecte les 6 principes d’architecture REST :

1. L’architecture Client-Serveur
2. L’absence d’état
3. La mise en cache
4. Le système par couche
5. Le code à la demande
6. L’interface standardisée

En d’autres termes, le service REST décrit sa propre utilisation avec chaque ressource retournée. Si et seulement si une API basée sur le web répond à ces six contraintes, elle peut être considérée comme une API RESTful.

L’architecture Client-Serveur

Cette contrainte garantit une séparation des responsabilités. Le client gère les problèmes d’interface avec l’utilisateur, tandis que le serveur gère les problèmes de stockage des données. En retour, nous obtenons un système dans lequel un service REST peut servir de nombreux clients et interfaces différents sans se soucier de l’aspect de ces interfaces ou de ce qu’elles font.

En bref, nous avons une séparation entre le contenu, sa présentation graphique et son interaction fonctionnelle.

L’absence d’état

Aucun contexte ou information du client, qu’on appelle état, ne peut être stocké sur le serveur entre les requêtes. Le client est responsable du suivi de son propre état de session et toutes les demandes envoyées par un client doivent être autonomes et complètes. Si l’état de la session du client est pertinent, il doit être envoyé avec une demande et si le serveur doit stocker cet état, il doit le transmettre à une base de données ou à un service similaire pour une durée spécifique.

Par exemple, on peut demander au serveur de transmettre un jeton d’authentification pendant une période déterminée afin de permettre les demandes authentifiées.

La mise en cache

Il s’agit de stocker les réponses de l’API pendant une période déterminée, cela fait partie intégrante de l’architecture Web et de l’optimisation des performances. Toutes les réponses REST doivent être clairement marquées comme pouvant être mises en cache ou non afin de garantir que la mise en cache fonctionne comme prévu du côté du client. Cela signifie qu’il faut mettre en cache les réponses qui ne changeront pas ou peu, mettre en cache les réponses rarement ou périodiquement modifiées pendant des périodes raisonnables, et bloquer la mise en cache des réponses qui changent constamment.

Le système par couche

Le système doit être conçu de manière à ce que le client ne puisse pas savoir et ne se soucie pas de savoir s’il est connecté directement au serveur ou à un intermédiaire comme un proxy ou un CDN. Cela garantit l’évolutivité et contribue également à la sécurité.

Le code à la demande

Les serveurs sont autorisés à transférer du code exécutable sous la forme de JavaScript côté client et de composants compilés au client pour étendre et personnaliser les fonctionnalités. Cela reste une utilisation moins courante donc je ne m’étendrai pas sur le sujet.

L’interface standardisée

Pour qu’elle soit uniforme ou standardisée, une interface doit pouvoir être identifiée facilement depuis la requête. Une URL est utilisée pour envoyer une requête et cette URL spécifie quelle ressource est recherchée. Ainsi, une URL comme auteur/florian/bio demanderait ma biographie comme ressource. La clé ici c’est que la ressource correspond à la donnée qui se trouve sur le serveur.

Ce que l’API renvoie est une représentation de cette ressource qui peut avoir un format différent de celui de la ressource stockée sur le serveur. Alors que les données peuvent être stockées dans une base de données au format SQL, la réponse renvoyée peut être au format JSON ou XML ou même HTML.

L’interface doit permettre la manipulation des ressources par le biais des réponses serveur. Cela signifie qu’une fois qu’un client a la représentation d’une ressource, il peut également modifier ou supprimer cette ressource. En d’autres termes, le client, s’il dispose des droits suffisants, peut contrôler ce qui est stocké sur le serveur.

Une interface doit émettre des messages autodescriptifs. Cela vaut tant pour l’envoi que pour la réception de données. Chaque représentation doit décrire son propre format de données. Ainsi, si vous recevez du JSON, l’entête renvoyée par le serveur dans la réponse sera de type JSON. Sans cette information, les données ne peuvent pas être analysées de manière fiable.

Enfin, une interface pour qu’elle soit dite « standardisée » doit utiliser l’hypermédia pour rendre compte de l’état de l’application. Il s’agit d’une façon compliquée de dire qu’une fois que le client a accès à une ressource REST, il devrait être en mesure de découvrir toutes les autres ressources et méthodes disponibles grâce aux hyperliens fournis. Demandez une ressource de page et, avec le contenu de la page, la représentation de retour devrait inclure des hyperliens vers toutes les ressources et méthodes disponibles.

Les méthodes HTTP

Les méthodes HTTP sont parfois appelées verbes HTTP. Il s’agit simplement des différentes manières de communiquer avec une API.

• La méthode GET est utilisée pour récupérer des données
• La méthode POST est utilisée pour créer de nouvelles ressources
• La méthode PUT est utilisée pour mettre à jour des ressources
• La méthode DELETE est utilisée pour pour supprimer des ressources
• La méthode OPTIONS est plus rare mais peut être utilisée pour fournir un contexte à des ressources