HTTP

Connectez votre app à une API grâce au composant HTTP. Vous pouvez l’utiliser pour afficher une collection externe, envoyer des données à un service tiers ou récupérer des informations en temps réel comme la météo, des disponibilités ou des données utilisateur.

Une API permet de rendre disponibles les données ou les fonctionnalités d’un service existant afin que d’autres applications puissent les utiliser. Dans PandaSuite, le composant HTTP sert à envoyer des requêtes, récupérer les réponses et exposer les données retournées pour les réutiliser ailleurs dans le projet.

Chaque API possède ses propres paramètres, règles d’authentification et formats de réponse. Le composant HTTP vous permet d’adapter votre configuration à cette documentation.

Ajouter le composant HTTP

Insérez le composant HTTP à l’endroit où il sera utilisé dans votre projet. Si la requête est réutilisée sur plusieurs écrans ou pilote un comportement global, placez-le au niveau du Projet.

Configurer la requête

URL

Vous avez besoin du point d’entrée de base fourni par la documentation de l’API.

Voici par exemple l’URL de l’API d’OpenWeatherMap :

https://api.openweathermap.org/data/2.5/weather?q={city name}&appid={API key}

Dans le champ URL, copiez-collez tout ce qui se situe depuis https: jusqu’au ?, sans inclure le ?. Le reste des informations doit être ajouté dans Chaîne d’interrogation.

En-têtes et paramètres de requête

Beaucoup d’APIs attendent des valeurs supplémentaires pour personnaliser la requête :

utilisez En-têtes pour les valeurs envoyées dans l’en-tête HTTP ;
utilisez Chaîne d’interrogation pour les paramètres ajoutés à l’URL.

Cette séparation rend la requête plus lisible et plus simple à maintenir si vous liez des valeurs dynamiques.

Autorisation

Si l’API nécessite une authentification, réglez Autorisation sur l’un de ces modes :

Aucune
HTTP Basic
Clé API

Avec HTTP Basic, renseignez Nom d’utilisateur et Mot de passe.

Avec Clé API, renseignez Clé et Valeur. C’est utile lorsque l’API attend un nom d’en-tête spécifique comme Authorization ou x-api-key.

Lorsque l’authentification est activée, le Mode proxy est utilisé automatiquement pour éviter d’exposer directement les valeurs sensibles dans l’application.

Cache

La mise en cache vous permet de réutiliser efficacement des données de l’API précédemment récupérées ou traitées. Ainsi les demandes futures sont traitées plus rapidement en accédant à l’emplacement de stockage principal des données et sans faire appel au réseau.

Choisissez le mode adapté à votre usage :

Aucun cache : l’application fait toujours un appel réseau.
Cache en premier : l’application recherche le résultat dans le cache avant de faire une requête au réseau.
Cache et réseau : l’application retourne d’abord le cache puis le met à jour via le réseau.
Réseau et cache : l’application privilégie le réseau et retombe sur le cache si nécessaire.

L’option Cache persistant permet de conserver le cache même après la fermeture de l’application.

Les requêtes envoyées avec Binary (application/octet-stream) passent toujours par le réseau et ne sont pas stockées dans le cache du composant HTTP.

Pour préparer des contenus API en hors connexion, consultez API & Données hors ligne.

Méthode et type de contenu

La propriété Méthode détermine le type de requête envoyé :

GET : requêter de la donnée depuis une ressource spécifique. C’est une des méthodes les plus courantes.
POST : créer une ressource.
HEAD : récupérer uniquement les en-têtes sans le corps de réponse.
PUT ou PATCH : mettre à jour une ressource.
DELETE : supprimer une ressource.

Pour les méthodes qui envoient un corps de requête, choisissez un Type de contenu :

Text (text/plain)
JSON (application/json)
Form (application/x-www-form-urlencoded)
XML (application/xml ou text/xml)
HTML (text/html)
Binary (application/octet-stream)

Le champ Contenu n’apparaît que lorsque la méthode choisie autorise un corps de requête.

Si vous choisissez Binary (application/octet-stream), le champ Contenu attend une source liée de type Image ou Video. Utilisez ce mode lorsque l’API attend directement le fichier média brut dans le corps de la requête, plutôt qu’un JSON ou un formulaire.

Activez Auto-ajout type de contenu si vous voulez que PandaSuite ajoute automatiquement l’en-tête Content-Type correspondant au format sélectionné. Désactivez-le seulement si l’API attend un en-tête personnalisé ou aucun en-tête de ce type.

Si votre objectif est de conserver des médias d’API disponibles hors ligne, exposez les champs de réponse en Image, Audio ou Video, puis suivez API & Données hors ligne. C’est différent du type Binary, qui sert à envoyer un fichier média dans le corps de la requête.

Autres options

Le composant propose aussi ces options :

Démarrage auto. : lance automatiquement la requête au chargement de la page ou de l’application.
Mode hors connexion : met les requêtes rejetées en file d’attente lorsque l’appareil est hors ligne, puis les renvoie une fois la connexion rétablie.
Mode proxy : fait transiter la requête par PandaSuite lorsque c’est nécessaire pour l’authentification ou pour certaines restrictions d’API.

Tester et exposer la réponse

Ouvrez la configuration du composant et cliquez sur Tester la requête.

Si la requête est valide, PandaSuite affiche la réponse brute. Vous pouvez alors cliquer directement sur des valeurs de la réponse pour les exposer et leur attribuer un type :

Chaîne de caractères
Booléen
Nombre
Image
Audio
Video
Pagination offset

Cette étape est particulièrement utile pour lier les champs retournés à d’autres composants, configurer la pagination ou préparer des médias pour le téléchargement hors ligne.

Configurer la pagination

Si l’API retourne un jeton de pagination ou un offset, cliquez sur cette valeur dans le résultat du test puis définissez son type sur Pagination offset.

Si les résultats se trouvent dans un tableau, activez Fusionner les résultats et indiquez le chemin de ce tableau, par exemple /records, pour que PandaSuite regroupe les éléments de plusieurs pages.

Lorsque vous déclenchez Lancer la requête, vous pouvez activer Boucle sur toutes les pages pour charger automatiquement toutes les pages.

Pour un pas à pas complet, consultez Gérer la pagination d’une API.

Déclencher et gérer les requêtes

Si vous n’utilisez pas Démarrage auto., ajoutez une action pour lancer la requête au bon moment.

Par exemple, sélectionnez un écran puis allez dans Actions > Affichage courant > Agir sur composant > Composant HTTP > Lancer la requête.

Le composant HTTP met à disposition ces actions :

Lancer la requête : démarre la requête. Pour les méthodes autres que GET et HEAD, vous pouvez aussi activer Remplacer la requête et envoyer un autre Contenu au moment de l’action. L’entrée disponible suit le Type de contenu choisi, y compris une source liée Image ou Video pour Binary (application/octet-stream).
Supprimer le cache : efface la réponse mise en cache pour ce composant.
Refaire les requêtes rejetées : relance les requêtes ayant échoué hors connexion.
Supprimer les requêtes rejetées : vide la file d’attente hors connexion.
Page suivante et Page précédente : naviguent dans les résultats paginés.

Il expose également ces événements :

Requête complétée : déclenché quand la requête réussit.
Requête rejetée : déclenché quand la requête échoue et expose le statut de réponse ainsi que le Corps de la réponse.