Requêtes HTTP - API
Accéder aux requêtes http
Comme toute plateforme nocode, UDo.tools dispose de son moteur d’api qui lui permet de venir interagir avec des systèmes tiers.
Vous y accédez via le menu data de la side bar du studio et l’onglet 🌐. Ensuite, il vous suffit de "créer une requête HTTP" puis de la nommer. Il faut considérer ce nom comme étant un regroupement de requête vers un même logiciel tiers. |
Une fois que vous avez cliqué sur le bouton en haut à droite, + NOUVELLE REQUETE, alors vous aurez accès aux paramètres de la requête. Cette fois ci, il s’agit vraiment d’une requête unitaire.
Ajout des détails de la requête
Une fois votre requête nommée de façon explicite, si vous souhaitez l’exécuter vous devrez connaître l’URL, la méthode et d’autres valeurs facultatives telles que auth et les paramètres.
Définition des URL de requête
Chaque demande que vous envoyez dans UDo.tools nécessite une URL représentant le endpoint de l’API avec lequel vous travaillez. Chaque opération que vous pouvez effectuer à l’aide d’une API est généralement associée à un endpoint. Chaque endpoint d’une API correspond à une URL particulière : c’est ce que vous entrez dans UDo.tools pour accéder à l’API.
-
Si vous créez une API, l’URL sera généralement l’emplacement de base plus le chemin. Par exemple, dans la requête
https://api-test-fun.glitch.me/info-
https://api-test-fun.glitch.meest l’URL de base -
/infoest le chemin d’accès au endpoint.
-
-
Si vous utilisez une API tierce, votre fournisseur d’API vous fournira les URL dont vous avez besoin, par exemple dans sa documentation développeur.
Il convient de toujours spécifier le protocole de connexion en http ou https.
Vous pouvez éventuellement saisir des paramètres de requête dans le champ URL ou les saisir dans l’onglet Query Params. Si votre requête utilise des path paramètres, vous pouvez les saisir directement dans le champ URL.
Sélection du type d’opération
Il existe plusieurs type d’opération pour consommer une API, ils sont généralement basés sur les verbes du protocole HTTP.
Par défaut, UDo.tools sélectionnera la méthode GET pour la nouvelle demande.
GET Ce type d’opération sert généralement à lire une information.
Les autres verbes du protocole HTTP utilisés pour les API sont POST, PUT, PATCH et DELETE. Ils sont généralement utilisés pour :
|
Par exemple, si vous travaillez avec une API pour une application de liste de tâches , vous pouvez utiliser une méthode GET pour récupérer la liste actuelle des tâches, une méthode POST pour créer une nouvelle tâche et une méthode PUT ou PATCH pour modifier une tâche existante.
Si votre demande ne nécessite pas de données de corps, d’authentification ou d’en-têtes, continuez et cliquez sur "TESTER" pour l’essayer. Sinon, configurez votre body, auth et headers .
Exemple d’API REST avec l’API Wikipédia
Prenons pour exemple l’API REST de Wikipédia qui est très complète et bien documentée.
Elle permet de nombreuses opérations différentes, notamment sur les pages (créer, éditer, supprimer une page, changer sa langue etc.) et sur les comptes (créer, bloquer, éditer un utilisateur et ses permissions etc.). Il s’agit d’une API Publique accessible via le protocole HTTP. Nous pouvons donc y faire des appels et lire les réponses directement depuis notre navigateur web.
L’une des actions les plus importantes et les plus utilisées sur l’API Wikipédia est la récupération de données. Voyons ensemble un exemple d’appel vers l’API Wikipédia pour récupérer un extrait du contenu d’une page :
Exemple d’appel à l’API REST de wikipedia
Analysons cet appel élément par élément pour bien le comprendre :
-
https://fr.wikipedia.org/w/api.php est l’endpoint de l’API REST, c’est-à-dire l’URL à laquelle envoyer les appels. L’API Wikipédia ne dispose que d’un seul endpoint, mais certaines APIs en ont plusieurs (par exemple : example.com/api/articles/edit.php et example.com/api/articles/create.php).
-
“action=query” est le premier paramètre de cet appel. Comme pour toute requête HTTP standard, le premier paramètre est toujours précédé d’un séparateur point d’interrogation (“?”). Vient ensuite le nom du paramètre (“action”) qui, selon la documentation de l’API Wikipédia, va définir le type d’action que l’on réalise. La valeur du paramètre est ici “query”, ce qui signifie pour l’API Wikipédia que l’on cherche à récupérer le contenu d’une fiche Wikipédia.
-
“titles=interface de programmation” est le deuxième paramètre de cet appel. Après le premier paramètre, tous les autres sont séparés par un séparateur esperluette (“&”). Le nom de ce paramètre est “titles”, ce qui définit le ou les titres des fiches Wikipédia que l’on cible avec notre appel. La valeur du paramètre est “interface de programmation”, c’est-à-dire que l’on va cibler la fiche Wikipédia de ce sujet ; mais on pourrait très bien essayer avec “Terre” ou “Charles de Gaulle” par exemple. L’API de Wikipédia nous autorise également à préciser plusieurs valeurs séparées par une barre verticale (“|”) pour obtenir les contenus de plusieurs fiches dans un seul et même appel. Par exemple : “titles=Terre|Mars|Lune|Jupiter”.
-
“prop=extracts” est le troisième paramètre. Il définit les différentes propriétés que l’on souhaite récupérer sur la fiche ciblée. Ici, la valeur du paramètre est “extracts” ce qui signifie, selon la documentation de l’API Wikipédia, que la réponse contiendra un extrait, limité ou non, du contenu textuel de la fiche. Là encore, l’API nous permet de préciser plusieurs valeurs séparées d’une barre verticale.
-
“exchars=500” est le quatrième paramètre. Il limite l’extrait de texte à 500 caractères.
-
“explaintext” est un paramètre booléen, c’est à dire qu’il n’a que deux valeurs possibles : vrai (souvent symbolisé 1 ou >true voire on) ou faux (souvent symbolisé 0 ou false voire off). Ce paramètre permet de retourner l’extrait en texte brut plutôt qu’en HTML. Étant désactivé par défaut, le simple fait de préciser le nom du paramètre permet de l’activer ; mais nous aurions pu définir ce paramètre de cette façon : “explaintext=1” ou “explaintext=true”.
-
“utf8” est le dernier paramètre de l’appel et est également un paramètre booléen. Il active, lui, l’encodage du texte en UTF-8.
Voyons maintenant la réponse renvoyée par l’API REST Wikipédia suite à notre appel :
{
"batchcomplete": "",
"query": {
"normalized": [
{
"from": "interface de programmation",
"to": "Interface de programmation"
}
],
"pages": {
"16680": {
"pageid": 16680,
"ns": 0,
"title": "Interface de programmation",
"extract": "En informatique, une interface de programmation d’applications ou interface de programmation applicative,, (souvent désignée par le terme API pour Application Programming Interface) est un ensemble normalisé de classes, de méthodes, de fonctions et de constantes qui sert de façade par laquelle un logiciel offre des services à d'autres logiciels. Elle est offerte par une bibliothèque logicielle ou un service web, le plus souvent accompagnée d'une description qui spécifie comment des programmes consommateurs..."
}
}
}
}Cette réponse est au format JSON et contient des informations, certaines que nous avons demandées, d’autres non. On y retrouve le titre de la fiche ciblée par l’API, ce qui nous permet de vérifier que nous avons bien récupéré le contenu de la fiche “interface de programmation” ; nous avons également l’identifiant “pageid” de la fiche, utile pour réaliser d’autres appels sur cette fiche ; pour finir, nous avons l’extrait que nous avons demandé, en texte plein, encodé en ut8 et limité à 500 caractères comme indiqué dans notre requête.
Headers
Les headers fournissent des méta-informations sur une requête. C’est une simple liste, comprenant par exemple l’heure à laquelle le client a envoyé la requête et la taille du body.
Si vous avez déjà visité un site web spécialement formaté pour votre smartphone, c’est grâce à un header HTTP appelé “User-Agent”, qui indique au serveur le type d’appareil que vous utilisez et les sites suffisamment intelligents pour le détecter vous retournent le meilleur format possible.
Body
Le body de la requête contient les données que le client souhaite envoyer au seveur.
Une caractéristique unique du body est que le client contrôle totalement cette partie de la requête. Contrairement aux méthodes, URL et headers, où le protocole HTTP impose une structure rigide, le body permet au client d’envoyer tout ce dont il peut avoir besoin.
Ces quatre parties - URL, méthode, headers et body - forment une requête HTTP complète.
Les réponses HTTP
Lorsque le serveur reçoit la requête du client, il s’efforce d’y satisfaire et envoie une réponse. Les réponses HTTP ont une structure assez similaire à celle des requêtes, la différence principale étant qu’à la place d’une méthode et d’une URL, la réponse inclut un code de statut. À part ça, les headers et body ont le même format que dans la requête.
Les codes de statuts
Les codes de statuts sont des nombres à 3 chiffres et ils ont chacun leur signification unique. Quand il est bien utilisé dans une API, ce petit nombre peut apporter beaucoup d’informations au client. Vous avez sûrement déjà déjà rencontré ce genre de message dans vos navigations sur le net :
Le code de statut est ici 404, ce qui signifie “pas trouvé” (not found). À chaque fois qu’un client fait une requête pour une ressource qui n’existe pas, le serveur répond avec un code statut 404 pour faire savoir au client que “cette ressource n’existe pas, ne la demandez plus svp”.
Il existe une kyrielle d’autres statuts dans le protocole HTTP, dont le statut 200 \(“succès ! cette requête était bonne”\) et le statut 503 \(“notre site ou notre API est en maintenance”\).
Après qu’une réponse ait été délivrée au client, le cycle requête-réponse est terminé, c’est maintenant au client d’initier de nouvelles interactions. Quant au serveur, il ne fait plus rien tant qu’il ne reçoit pas de nouvelle requête.
Pour une mise en pratique de ces éléments vous pouvez vous reporter au tutoriel Quête 3 - Chevalier vétéran - Leçon 38 - API (Requête HTTP)
