Salut et bienvenue dans ce nouvel épisode du podcast de Code Garage, je m'appelle Nicolas
Brondin-Bernard et aujourd'hui on va parler de ce qu'est une API REST.
Alors il faut d'abord commencer par rappeler ce qu'est une API, une Application Programming
Interface.
C'est un ensemble de fonctionnalités qui sont disponibles au travers d'une couche d'abstraction
simplifiée et qui permettent de développer un logiciel grâce à la consommation justement
de ces dernières de l'API.
Alors si jamais le concept d'API vous n'est pas parfaitement familier, je vous renvoie
un ancien épisode du podcast où on parle justement des API, de la différence entre
une API et un SDK.
Je vous mettrai le lien de cet épisode dans les notes du podcast.
Donc cette définition, pardon, que je viens de donner, elle est valable pour les API REST,
les API GraphQL, SOAP, etc.
Mais qu'est-ce qui différencie réellement une API REST des autres ?
C'est ce qu'on va voir ensemble.
Donc les principales caractéristiques d'une API REST, c'est d'abord que c'est une
API qui est conçue pour le web.
Certaines APIs sont mises à disposition par le système de l'exploitation, par le navigateur
et d'autres par des serveurs disponibles sur Internet.
Et bien le concept de REST est basé justement sur le protocole HTTP.
Il est donc indissociable d'Internet et plus précisément du web.
Alors bien sûr, une API REST, elle peut être consommée depuis n'importe quel système,
langage, etc.
Le seul prérequis, c'est la possibilité d'effectuer des requêtes HTTP.
Ensuite, l'autre caractéristique, c'est les états versus les transactions.
Donc il faut savoir que REST, ça signifie representational state transfer.
La représentation du transfert des états.
Et cette définition, elle n'est pas vide de sens parce que certaines APIs, SOPE, GraphQL
par exemple, proposent une abstraction basée sur des transactions.
Par exemple, ça va être sous forme de méthode, on va avoir list article, create or update
article et on va envoyer des données, delete article et on va envoyer des id.
Ici, le terme transaction, il est synonyme d'un ensemble d'opérations de fonctions
exécutées dans un certain ordre.
Quand on va avoir create or update article, on ne va pas avoir une seule opération mais
on va avoir un enchaînement d'opération potentiellement.
REST, il est basé sur la représentation directe des données.
Donc au lieu d'exposer les transactions qui sont disponibles, une API REST, elle expose
des ressources sous la forme d'URL pour représenter directement l'état de ces données.
Par exemple, je vais avoir un GET, slash articles, ça va retourner tous les articles.
Un GET, slash article slash one, ça va retourner les détails de l'article 1.
Si je fais un appel POST slash articles, on va créer un nouvel article et on va le retourner.
Un POST slash articles slash one, ça modifie l'article 1 et retourne l'article modifié.
Et puis un DELETE slash article slash one, ça va supprimer l'article 1.
Ici, on peut voir que chaque appel n'affectera que la ressource en question et que chaque
méthode pour mettre à jour une ressource est indépendante.
Par exemple, pour créer le même comportement que la transaction précédente, par exemple
create or update article, il faudra faire un appel GET, puis un appel POST ou un appel PUT
selon si on crée ou on met à jour. Voilà pourquoi on parle de représentation des
données et pas de transactions pour une API REST. Ensuite, ça, c'était un petit peu
les caractéristiques d'une API REST, mais il existe des règles pour les API qu'on appelle RESTFULL.
Si on résume le concept d'API REST, c'est une API qui permet de récupérer et modifier des ressources
grâce à des appels et des méthodes HTTP. Mais pour aller plus loin et concevoir une API RESTFULL
normalisée, RESTFULL, ça veut dire qui respecte toutes les règles de REST, il y a six règles à
respecter. Si et seulement si ces contraintes architecturales sont respectées, on parlera
alors d'une API RESTFULL. Donc voilà les six contraintes à respecter pour faire les choses dans
les règles de l'art. La première règle, c'est avoir une interface uniforme. Une interface
uniforme, ça veut dire que chaque appel à l'API aura la même forme, que chaque type d'appel doit
avoir le même comportement et que chaque réponse sera formulée de la même manière. Alors cette
uniformisation apporte principalement sur la manière dont chaque ressource est ciblée, comment les
données sont transmises et quelles sont les opérations qui leur sont appliquées. Donc pour
respecter cette règle, il y a quelques points importants. D'abord, une URI égale une ressource. La
partie la plus importante d'une requête, c'est la ressource. Elle est représentée par l'URI.
URI, c'est Unique Resource Identifier. Et une URI, elle peut contenir des paramètres pour spécifier
une ressource précise, comme on l'a vu un petit peu tout à l'heure avec les articles. Là, si on
prend la même chose avec des maisons, eh bien Slash Houses, c'est la liste de toutes les maisons.
Slash Houses Slash One, c'est le détail de la maison numéro 1. Slash Houses Slash One Slash Rooms,
eh bien c'est la liste des pièces de la maison 1, etc. Donc ça, c'est comment on
représente les ressources. Ensuite, il y a chaque méthode HTTP égale une action. Donc pour agir sur
une ressource, on va exploiter les méthodes HTTP. Donc pour ça, eh bien une méthode GET, ça va être
pour lister, récupérer ou une ou plusieurs ressources. POST, ça va être pour créer une ressource.
POST, ça va être pour mettre à jour une ressource et DELETE pour supprimer une ressource,
ce qui paraît plutôt logique. Alors la bonne conception d'une API RESTFULL,
elle réside notamment dans le respect des règles sémantiques d'HTTP comme notamment
l'idempotence. Si jamais l'idempotence, ça ne vous parle pas, eh bien vous pouvez aller voir,
j'ai aussi créé un épisode, enregistré un épisode, il y a quelques temps,
je vous mettrai le lien dans les notes. Ensuite, on a la règle qui fait que le corps de la requête,
ce sont les données. Les données qu'on va appeler payload parfois, elles sont passées dans le corps
de la requête pour les méthodes HTTP qu'ils permettent. En l'occurrence, les requêtes POST et PUT.
Il n'y a pas de limitation sur le format des données qui sont passées à l'API. On utilise souvent
le format JSON, mais on peut trouver des API qui acceptent le XML ou un blob directement, etc.
Certaines API acceptent et même renvoient plusieurs types différents parfois, en rapport avec les
informations qui sont contenues dans les entêtes acceptes et content type. Donc ça, c'est une règle
qui n'est pas stricte, mais quand même on dit que le corps de la requête, ça contient les données.
Et si le corps de la requête contient les données, les entêtes contiennent les métadonnées. Toutes
les informations supplémentaires requises par l'API pour son bon fonctionnement, ça peut être les
données d'identification, la langue, les choses comme ça, seront communiquées par les entêtes des
requêtes. Donc par exemple les entêtes authorization, accepte language, etc. Ensuite, les codes de
statut sont égaux aux résultats qu'on va recevoir. Le résultat des opérations effectuées par l'API
devra toujours être représenté par le code de statut HTTP correspondant, toujours en gardant
que la sémantique de l'API doit être le plus explicite possible. Donc par exemple quelques exemples
de codes de retour, 200 c'est un succès, 201 c'est un succès plus le fait qu'une nouvelle
ressource a été créée, 404 c'est qu'une ressource est introuvable, 400 c'est qu'il y a un problème dans
la requête, etc. Alors un des exemples à éviter par exemple, c'est le renvoi d'un code 200 avec un
message d'erreur à l'intérieur dans le corps de la requête. C'est d'ailleurs l'une de ces
caractéristiques qui différençaient une API REST d'une API GraphQL. C'est quand GraphQL,
un peu tout est renvoyé dans le corps de la réponse alors qu'en reste on va vraiment utiliser
au maximum les codes de statut. Pareil, si jamais vous ne connaissez pas bien les codes de retour HTTP,
j'ai un article dédié pour le coup je vous le mets dans les notes de l'épisode.
Et enfin la dernière règle, on va dire sous règle d'une API RESTful, c'est ce qu'on appelle,
alors là l'acronyme est un petit peu barbare, c'est HATOAS. HATOAS donc c'est H-A-T-E-O-A-S.
Ça signifie hypermédia as the engine of application state. Et derrière cet acronyme,
ce cache en réalité un concept qui est assez simple. Une API RESTful, c'est pas seulement
censé fournir les données d'une ressource mais c'est censé également fournir les liens,
donc des liens hypertexte directs vers les ressources connexes dans le but de rendre
le parcours de ressources plus simples et automatisables. Qu'est-ce que ça veut dire ?
Ça vous donnera les détails d'un article de blog avec le nom de l'auteur par exemple.
Mais donc ça contiendra pas que ça évidemment mais ça contiendra entre autres le nom de
l'auteur ou de l'autrice. Mais la réponse devra également contenir un lien vers api.exemple.com
slash autor slash 2637 dans l'objet de l'auteur. Ça veut dire que directement avec la contenue de
cette réponse-là, je vais pouvoir construire une autre requête vers mon API REST directement avec
cette URL-là pour récupérer toutes les infos dont j'aurai besoin éventuellement. On parle
d'une API dont on peut parcourir le contenu de manière plus ou moins automatisée. L'une des
autres règles évidemment d'une API RESTful, c'est le côté client-server. Cette contrainte
apparaît évidente quand on compare par exemple une API RESTful à du GraphQL mais comme expliqué
au début de l'épisode, il y a beaucoup d'API qui sont mises à disposition par le système et non au
travers d'un serveur différent. Donc une API REST, elle fonctionne selon une architecture client-server
obligatoirement. Ensuite, il y a le fait qu'une API RESTful, elle doit être sans état. On parle
aussi de STATEless. La contrainte sans état, ça décrit un mode de fonctionnement dans lequel
aucune information n'est conservée sur le serveur entre deux appels consécutifs. L'exemple
le plus parlant, ça reste celui de l'authentification. En utilisant un système de session stocké sur
le serveur, le serveur en question conserve un état en mémoire. On parle alors d'un fonctionnement
STATEful ou avec état. Une API STATEless, elle va plutôt utiliser une authentification par token,
par exemple, et les informations de l'utilisateur, elles seront stockées dans une base de données
serialisée et récupérées à chaque nouvelle appel grâce aux jetons fournis dans chaque requête.
Ça permet notamment de déployer son API sur plusieurs machines pour passer à l'échelle,
ce qu'on appelle le scaling de manière horizontale, sans risquer de perdre l'état actuel d'une machine
et donc par exemple dans notre exemple l'authentification d'un utilisateur. Ensuite,
la quatrième règle, c'est la mise en cache. Contrairement à certains autres types d'API ou
le cache, c'est pas la priorité. Les appels de lecture get d'une API restful doivent pouvoir
être mis en cache pour optimiser les performances au niveau de la récupération de données. Comme
toujours, on se base sur toutes les fonctionnalités qu'offre le protocole HTTP et on s'en sert au maximum.
La cinquième règle, c'est un système à plusieurs niveaux. Cette contrainte,
elle ne signifie pas que votre API se doit de contenir plusieurs niveaux mais peut contenir
plusieurs niveaux. Par exemple, on peut imaginer que votre serveur d'API tourne derrière un certain
nombre d'autres serveurs comme un serveur de cache, un proxy ou un reverse proxy, un répartiteur de
charge, etc. La contrainte ici, c'est que les requêtes et les réponses de votre API restent,
ne doivent pas être impactées par ces intermédiaires et donc ça doit être absolument
transparent pour le client qui envoie et reçoit les requêtes et les réponses.
Et enfin, la sixième et dernière règle d'une API restful, celle-ci, elle est optionnelle. C'est
le Code On Demand. La contrainte de Code On Demand, c'est la celle qui est optionnelle parce que ça
répond pas aux besoins de tous les projets et parce qu'il peut y avoir quelques implications en
termes de sécurité. En théorie, un client peut être capable de demander du code à une API restful
qui sera alors contenu dans le corps de la réponse pour être exécuté sur le client.
Alors par exemple, on peut imaginer une balise script récupérée et contenant une méthode de
calcul spécifique pour une donnée qui sera utilisée par le front-end d'une application. On peut imaginer
ça dans des cas d'utilisation dans le H-computing par exemple ou même ça peut être une expression
régulière pour valider plus facilement une donnée. Évidemment, cette donnée sera également
validée côté serveur mais on aura une validation qui sera un peu plus dynamique côté client. Donc
ça, c'est la sixième règle mais qui est vraiment optionnelle puisqu'elle ne le correspond pas à tous
les projets. Ça a été un épisode un peu plus long que les épisodes d'habitude mais parce que le
concept d'API rest est important. Il est assez complet surtout quand on rentre dans le cas d'une
API restful. Donc n'hésitez pas à réécouter ce podcast plus tard si jamais vous en avez besoin.
Je vous mets aussi dans les notes de l'épisode le lien vers la version écrite. On vous retrouverait
quasiment exactement les mêmes informations que dans cet épisode du podcast. En tout cas,
j'espère que cet épisode vous aura aidé et moi je vous dis à la semaine prochaine pour un
prochain épisode du podcast ou bien à tout de suite sur code-garage.fr. Code garage c'est un site
avec des cours, des formations pour les développeurs et les développeuses qui souhaitent continuer à
se former. C'est un abonnement un petit peu à la Netflix mais ou pour l'abonnement de 19h
ou 49 par mois, vous avez accès à toutes nos formations et tous nos cours. À la semaine prochaine,
salut !