Qu'est-ce qu'une API REST ?

Qu'est-ce qu'une API REST ? Cette question peut être décomposée en 3 questions distinctes :

1. Qu'est-ce qu'une API, en général ?
2. Qu'est-ce qu'une web API, et comment l'utiliser ? À quoi cela sert-il ?
3. Qu'est-ce qu'une API REST ? Comment les API RESTfull sont-elles organisées ?

Aujourd'hui, nous allons nous mettre dans la peau d'un développeur full-stack qui doit mettre en place un site web pour une librairie. Et comme notre développeur imaginaire veut bien faire son travail, il va mettre en place une API. Qu'est-ce qu'une API ? Et pourquoi notre développeur veut-il en créer une ?

Concept général : qu'est-ce qu'une API ?

Une API est l'abréviation de "Application Programming Interface" (interface de programmation d'applications). Il y a deux parties à cela : La programmation d'applications, d'une part, et l'interface, d'autre part. Tout d'abord, qu'est-ce qu'une "interface " ?

C'est très simple. Le nom dit tout. Le mot "interface" est inter / face. C'est quelque chose qui se trouve entre (inter) deux choses qui se font face. Par exemple, la surface de la mer est l'interface entre l'eau et l'air.

Souvent, lorsqu'on parle d'interface, il s'agit de la partie de l'écran qui explique ce que fait le logiciel et qui permet à l'utilisateur d'interagir avec lui. Dans ce cas, l'interface est ce qui relie l'utilisateur au logiciel. C'est pourquoi nous parlons d'interface utilisateur (IU), qui est la "surface" entre l'homme et le logiciel.

Dans le cas de l'API, les deux entités qui interagissent sont des éléments de code. Nous parlons de l'API d'une bibliothèque logicielle lorsque nous nous référons à la liste des fonctions publiques qu'elle fournit. Cela inclut leur signature, c'est-à-dire le type de paramètres que ces fonctions acceptent et ce qu'elles renvoient.

Mais le plus souvent, aujourd'hui, lorsque nous parlons d'API, nous parlons de communication via l'internet, via le web. La communication web que nous connaissons le mieux se produit lorsqu'un navigateur demande une page web, à laquelle le serveur renvoie beaucoup de HTML et de CSS.

Ici, dans le cas d'une API, un morceau de code (Javascript, par exemple) envoie une requête au serveur. Et le serveur répond dans un format qu'un ordinateur peut comprendre. De nos jours, nous préférons souvent les retours JSON car ils sont également lisibles par nous, les humains limités.

Mais au début, les ordinateurs répondaient en XML. Ce XML était le "X" d'une technologie qui a fait fureur à une époque, mais qui s'est aujourd'hui perdue dans la masse : AJAX. Mais il vaut la peine de se demander pourquoi cette technologie était si à la mode. Et derrière cela se cache la question suivante : quel est l'intérêt des API web ?

À quoi servent les API Web ?

Les API Web sont ce qui fait fonctionner Angular, Vue, React et tout ce que l'on appelle le Web 2.0. Dans le Web 1.0, l'utilisateur demande une page, le serveur la renvoie et elle est actualisée.

Dans le Web 2.0, et dans les frameworks frontaux en général, nous n'avons plus besoin de rafraîchir la page pour accéder à de nouvelles informations, à un nouvel état de notre site. En effet, le code téléchargé dans notre navigateur appelle de lui-même le serveur et met à jour l'affichage sans qu'il soit nécessaire de changer de page.

Par exemple, si vous cliquez sur le bouton "suivre", à droite de cet article, la page n'est pas rechargée. Il met à jour l'état du bouton sans recharger la page. Essayez-le et constatez par vous-même !

Comme vous pouvez le constater, l'appel à une API web permet d'obtenir un contenu dynamique, sans avoir à attendre le chargement d'une page. Prenons un exemple simple. Supposons que vous vous demandiez dans quelle ville passer votre week-end. Vous entrez le nom d'une ville dans une barre de recherche. Vous commencez à taper L.

La barre de recherche se met à jour avec une liste déroulante. Elle contient le nom des villes et le temps qu'il fait actuellement : Londres, pluie, 20°. Liverpool, soleil, 10°, Lyon, Leeds... etc.

Bref, le code téléchargé dans votre navigateur peut vous guider directement. Et tout cela parce que ce code a envoyé un message web au serveur. Il a dit : "hé, donnez-moi le nom des villes qui commencent par L, avec leur météo actuelle". Et le serveur a répondu par un document JSON qui fournit toutes les informations dont vous avez besoin.

Voilà ce que sont les API web.

Il convient de préciser qu'il existe différents formats d'API web. Il existe un format de référence par défaut, le roi de la meute en quelque sorte. Ce format est utilisé dans de nombreux tutoriels et dans de nombreuses API publiques. Le fait qu'il soit facile à expliquer et à comprendre y est pour quelque chose. Ce format est REST (REpresentational State Transfer).

Il existe un autre format d'API web plus à la mode, créé par Facebook et appelé GraphQL. La philosophie de GraphQL est radicalement différente, mais cela mérite un article à part. Pour l'instant, examinons la structure des API REST et la manière dont elles sont construites.

Qu'est-ce qu'une API REST ?

Pour commencer, vous devez savoir que les actions HTTP (ou verbes) ont des significations associées. Lorsque vous ouvrez une page web, votre navigateur effectue une requête "GET". Lorsque vous soumettez un formulaire, votre navigateur envoie généralement une requête "POST" ou, dans certains cas, une requête "PUT". Enfin, lorsque vous demandez la suppression d'un élément, votre navigateur peut envoyer une requête DELETE.

Que signifient ces termes ? Une requête HTTP GET est une requête de lecture. Une requête POST est une requête de création de ressources. Une requête PUT est une requête de modification de ressource. Et une requête DELETE est une requête de suppression de ressource. Nous avons parlé de ressources, mais qu'est-ce qu'une ressource ?

Si vous savez comment fonctionne une base de données relationnelle, une ressource est très similaire à une ligne dans une table, c'est-à-dire un élément dans ma base de données. Revenons à notre site web de librairie. Ma base de données contient des livres et des auteurs. Il s'agit dans les deux cas de collections de ressources. Je vais donc associer un point d'entrée (c'est-à-dire une URL) à chacune de ces ressources. Disons que mon API se trouve à "/api" (par exemple sur localhost:8000/api ou sur yourserver.com/api). Le point d'entrée pour les livres sera donc "/api/books/". Pour les auteurs, ce sera "/api/authors/". Je vais donc interagir avec ces points d'entrée, en fonction de ce que je veux faire.

Commençons par lire les données. Nous ferons donc des requêtes GET. Par exemple, disons que je veux récupérer tous les auteurs que j'ai dans ma base de données. Dans ce cas, je vais faire une requête GET au point de terminaison des auteurs, "/api/authors". Il s'agit de la requête la plus simple, qui récupère l'ensemble de la collection.

Imaginons maintenant que je sache que l'auteur qui m'intéresse (disons... Douglas Adams) a l'identifiant 42 dans la base de données. Pour récupérer ses informations, j'envoie une requête GET à "/api/authors/42". Ce chemin, auquel est ajouté l'identifiant, identifie la ressource auteur qui m'intéresse.

On peut même imaginer vouloir récupérer des informations spécifiques sur un auteur, comme son nom. Dans ce cas, nous pourrions envoyer une requête GET à "/api/authors/42/lastname" qui récupèrerait le nom (ici, Adams).

Si nous voulons aller encore plus loin, nous pourrions imaginer vouloir récupérer la collection de livres écrits par notre auteur. Dans ce cas, nous enverrions une requête GET à "/api/authors/42/books".

Un petit mot sur les différences entre REST et GraphQL

Maintenant, deux petits détails ici, en passant, pour comparer REST et GraphQL.

Le premier est que l'accès au champ "books" de "/api/authors/id" est une façon de suivre le standard REST. Mais le créateur de l'API peut très bien avoir fait des choix architecturaux différents. Et c'est également vrai pour d'autres API dans la nature. Les API peuvent être plus ou moins RESTful. Ce n'est pas seulement noir ou blanc.

Et donc la seule façon de savoir ce qui est implémenté est de lire la documentation - s'il y en a une !- ou le code. L'avantage de GraphQL est qu'il est auto-documenté par nature : vous pouvez envoyer une requête à l'API graphQL qui renvoie la documentation. (C'est ce qu'on appelle "l'introspection"). Et cela permet beaucoup de choses, comme des aires de jeux avec autocomplétion.

L'autre différence est qu'en utilisant REST, vous pouvez soit récupérer tous les champs, soit un seul. Il n'y a pas d'intermédiaire, si vous voulez seulement spécifier 3 champs sur les 50 que vous voulez récupérer, vous ne pouvez pas. Et c'est là l'autre avantage de GraphQL : il vous permet de définir la forme des données que vous souhaitez récupérer. 
 
Mais revenons à notre API REST.

Des requêtes plus avancées

Imaginons que nous voulions créer un nouveau livre. Tout ce que nous avons à faire est d'envoyer une requête POST, avec tous les champs remplis, au point d'entrée "/api/books". Si nous voulons créer un auteur, nous enverrons les données de la requête à "/api/authors".

Maintenant, si nous voulons mettre à jour notre auteur, nous envoyons une requête PUT au chemin qui "appartient" à l'auteur (c'est-à-dire avec l'identifiant à la fin), avec les nouvelles données. Et si cela a été mis en œuvre, nous pourrions imaginer d'envoyer une requête PUT à un seul champ de la ressource. Par exemple, nous pourrions envoyer une requête PUT à un seul champ de la ressource : "/api/auteurs/42/date_de_naissance"

Et bien sûr, si nous voulons supprimer des données, nous envoyons une requête DELETE au point d'entrée qui correspond à ce que nous voulons supprimer.

En conclusion

Il y aurait beaucoup plus à couvrir, comme l'"idempotence", l'authentification et l'autorisation, et les codes de réponse HTTP, mais cela ferait l'objet d'un article beaucoup plus long. En attendant, j'espère que cet article vous a été utile. Si vous avez besoin d'aide, si vous avez des questions, n'hésitez pas à m'en faire part dans les commentaires.