MSGRAPH #1 - Les bases d'une API web

Définition d’une API

Définition de la CNIL :

Une API (application programming interface ou « interface de programmation d’application ») est une interface logicielle qui permet de « connecter » un logiciel ou un service à un autre logiciel ou service afin d’échanger des données et des fonctionnalités.

Dans la plupart des cas, une API est positionnée comme un intermédiaire permettant de faciliter les échanges entre clients et serveurs. Les clients savent comment récupérer l’information et le serveur sait comment la formater correctement. Les deux peuvent donc communiquer de manière standardisée, sans nécessiter plus d’information sur le contexte de l’un ou de l’autre.

Standard REST

Il existe différents types d’API, mais le standard le plus répandu pour les API web est le REST (Representational State Transfer). Chaque API RESTful est différente puisqu’il ne s’agit que de lignes directrices, mais elles s’articulent obligatoirement autour de ces deux élements :

1. La méthode : comment voulez-vous interagir avec la donnée
2. L’URI : pour identifier la ressource que vous voulez requêter

On peut également retrouver un Body (corps de message) et un Header (entête) pour envoyer de la donnée et s’authentifier.

Ces éléments vont permettre de construire une requête HTTP pour pouvoir interagir avec une donnée précise.

Méthode

Il existe quatre méthodes principales :

• GET pour récupérer de la donnée
• POST pour ajouter de la donnée
• PATCH pour mettre à jour de la donnée
• DELETE pour supprimer de la donnée

Il en existe d’autre, mais les quatre cités précédemment représentent plus de 90% des requêtes.

URI

Une URI (Uniform Ressource Identifier), elle se compose en général de trois parties :

1. Le FQDN du site web que l’on veut requêter : http://www.reddit.com/
2. Le chemin vers la ressource qui nous intéresse : r/midjourney
3. Les paramètres de requête pour filtrer, sélectionner ou trier : /top.json?t=month

On obtient alors notre URI complète : http://www.reddit.com/r/midjourney/top.json?t=month

Clients REST

Le client API REST le plus connu est Postman, qui permet d’avoir une interface utilisateur simple et de requêter sans avoir besoin de coder

Si vous souhaitez coder, quasiment tous les langages de programmation modernes proposent une méthode pour envoyer des requêtes HTTP vers une API. Pour PowerShell, vous pouvez utiliser les commandes Invoke-RestMethod et/ou Invoke-WebRequest.

Pour de la récupération de données (méthode GET) sur une API ouverte à tous, vous pouvez même utiliser simplement votre navigateur et aller à l’URL indiquée pour consulter le résultat.

Résultat

Le résultat d’une requête sera fourni dans un langage structuré. Le plus souvent, les résultats seront donnés en JSON (avec souvent une indication sur le format de réponse utilisé).

Faire une requête HTTP

Pour faire une requête via PowerShell, vous pouvez utiliser la commande Invoke-RestMethod puis indiquer votre méthode et l’URI :

$uri = 'https://restcountries.com/v3.1/alpha/FR'
Invoke-RestMethod -Method 'GET' -Uri $uri

Vous pouvez également utiliser Postman pour effectuer votre requête :

Exercice pratique

Nous allons mettre en pratique les différents éléments abordés dans un exercice utilisant une API RESTful très simple à utiliser. L’idée de cet exercice est de faire des requêtes GET depuis PowerShell ou un client (comme Postman) sur une API simple et ouverte à tous.

À l’aide de l’API Découpage Administratif (api.gouv.fr), vous devez répondre aux questions suivantes :

• Combien y’a-t’il de communes dans le département 75 ?
• Combien y’a-t’il d’habitants à Louvemont-Côte-du-Poivre (code : 55307) ?
• Récupérer la liste des départements d’une des régions française
• (BONUS) Lister les cinq plus grandes villes de votre département de naissance
• (SUPER BONUS) Quelle est la région la moins peuplée ?

Vous pouvez utiliser PowerShell avec la commande Invoke-RestMethod, Postman ou encore l’outil intégré à la documentation de l’API.

Voir la solution