Une API REST est le type le plus utilisé et le plus fréquent d’API sur internet.
REST signifie "REpresentational State Transfer" et wikipedia vous dira tout sur le sujet si vous souhaitez l’approfondir.
Ce qu’il nous semble important ici de retenir est le suivant. Utiliser une API REST sur internet, c’est interroger un serveur tiers en utilisant les mêmes méthodes que ce que propose l’affichage de page web ou des formulaires inclus dans ces mêmes pages web. Ainsi on va interroger ce serveur à partir d’une URL communiquée par l’éditeur de l’API.
Cette interrogation va se faire suivant différentes méthodes : GET, POST, PUT et DELETE. Pour qui parle un peu anglais, le nom de la méthode indique parfaitement l’action qu’on va vouloir réaliser ! En général, c’est GET (obtenir) et POST (poster, donc envoyer) qui sont le plus utilisées. D’ailleurs si vous utilisez internet, vous faites du GET et du POST tous les jours sans le savoir : demander l’affichage d’une page web à partir de son adresse, c’est faire une action GET. Remplir un formulaire sur une page et le valider, c’est faire une action de type POST.
Point important maintenant, il ne s’agit pas simplement de faire des requêtes vers une API, il faut aussi savoir ce qu’elles provoquent ! En règle générale, une requête provoque en retour la réception d’une réponse. Cette réponse, comme une page web l’est pour une adresse demandée dans un navigateur, est une suite de données renvoyées à l’expéditeur avec le résultat de la requête. Deux grands formats de retour d’information sont utilisés : le JSON et le XML. Parfois on peut choisir dans une API quel format recevoir en retour.
Ceci étant dit, les API bien conçues sont souvent très facilement lisibles, si on accepte de ne pas se laisser intimider par la documentation. Imaginons un service qui permettent d’obtenir des renseignements sur les livres et, pourquoi pas, d’ajouter de nouveaux livres à son catalogue.
Si je suis utilisateur, je vais vouloir extraire des informations sur un ouvrage à partir, par exemple, de son ISBN. Comme il s’agit d’obtenir une information, il faudra faire une requête GET à une adresse précisée par la documentation. Imaginons que cette adresse soit :
http://api.livresinfos.com/chercher/livres/isbn/9782294748790/
On comprend aisément qu’il s’agit de chercher des infos sur un livre par l’ISBN passé en fin d’adresse. Il y a fort à parier ici que cette API renverrait quelque chose du genre :
isbn : 9782294748790
titre : Guide de thérapeutique Perlemuter 2017
auteur : Léon PERLEMUTER | Gabriel PERLEMUTER
...
Le résultat de la recherche par ISBN ne pouvant être qu’unique (ou nul si l’ISBN n’existe pas), un seul résultat serait renvoyé
Imaginons maintenant une recherche plus vague :
http://api.livresinfos.com/chercher/livres/auteur/Perlemuter/
Il s’agirait donc ici de rechercher tous les livres dont les auteurs ont "Perlemuter" dans leur nom. Cela est possible, mais le résultat risque de contenir un très grand nombre - trop grand nombre - d’entrées. Il est très probable dans ce cas de figure que notre API propose d’abord de trouver l’auteur et l’identifiant unique que le service lui a attribué puis secondairement de chercher tous les livres écrits par cet auteur / identifiant unique.
Voilà pour l’esprit des requêtes GET permettant d’obtenir des données via une API REST.
Pour envoyer des données, cela fonctionne de la même façon, mais via l’action POST. Il faut alors dans ce cas typiquement imaginer un formulaire comme vous en voyez et pouvez en remplir partout sur le web. Ce formulaire est envoyé à l’API là encore sur une adresse spécifique, mais cette fois, les paramètres sont gérés comme autant de champs de formulaire. Comme il s’agit d’insérer de l’information dans le service tiers (pour lui faire exécuter des actions le plus souvent : envoi de messages par exemple), les données envoyées en retour sont souvent un accusé de réception qui contient une référence (un identifiant unique) permettant d’obtenir par la suite (en GET !) des informations sur le devenir de votre demande (message traité, message envoyé, message ouvert par le destinataire ...).