Pour surveiller correctement une API, il faut souvent utiliser plusieurs requêtes HTTP. En général, cela demande de mettre en place une séquence de requêtes, où chaque nouvelle requête utilise une ou plusieurs données extraites d’une requête précédente pour effectuer sa tâche.
Voici les raisons possibles de vouloir exécuter une séquence de requêtes HTTP :
- Votre API nécessite un accès authentifié. Pour appeler une méthode dans l’API, un client API doit d’abord s’authentifier (par exemple au moyen du protocole OAuth).
- Vous voulez tester un scénario fonctionnel dans votre API qui comprend plusieurs étapes généralement exécutées dans un certain ordre par vos utilisateurs finaux.
- Une de vos requêtes HTTP renvoie un redirect à une URL différente, mais vous souhaitez inspecter cette réponse avant d’effectuer la redirection.
Pour tous ces scénarios, la surveillance d’API multi-étapes (ou Multi-step API Monitoring) est un excellent choix.
Un scénario API peut être constitué d’une seule étape, mais vous pouvez y ajouter d’autres étapes voire étendre vos scénarios dans un second temps. Vous avez le contrôle total sur le contenu complet de la requête HTTP. Les fonctions suivantes sont disponibles :
- Configurer la méthode HTTP, l’URL, l’en-tête et le corps pour chaque requête
- Ajouter une authentification (Basic/NTLM/Digest/OAuth) ou inclure les certificats clients pour accéder aux fonctions protégées.
- Définir des assertions (vérifications) pour chaque réponse pour vérifier le code de statut HTTP, le contenu (d’après le texte brut ou un contenu JSON ou XML), la durée de la requête et d’autres données.
- Extraire du contenu du corps de la réponse, des en-têtes de réponse, des cookies et les stocker dans des variables. Ces variables peuvent être utilisées ultérieurement pour créer d’autres URL, en-têtes de requêtes, etc.
Grâce à ces fonctions, vous pouvez vous assurer que votre API se comporte correctement et s’exécute dans les limites que vous avez définies. Grâce aux instructions détaillées, vous pourrez commencer à configurer des scénarios très puissants sans ajouter de complexité. Si vous savez comment votre API doit se comporter, vous n’avez pas besoin de compétences en programmation pour démarrer la surveillance d’API.
Création d’un moniteur API multi-étapes
Pour ajouter un moniteur API multi-étapes :
Cliquez sur le bouton + dans le menu .
- Ouvrez le menu et cliquez sur le bouton + (Ajouter).
- Dans la fenêtre contextuelle Sélectionnez un type de moniteur, cliquez sur le type de moniteur Multi-step API, puis sur le bouton .
Le nouveau moniteur est créé et la page de configuration s’affiche. - Donnez un Nom à votre moniteur.
- Choisissez l'intervalle de vérification. L’intervalle de vérification correspond au temps écoulé entre la fin d’une vérification et le début de la suivante.
- Ouvrez l’onglet Étapes pour saisir les détails de chaque étape.
Votre nouveau moniteur contient déjà une étape (vide). Continuez et cliquez sur Ajouter une étape de requête pour ajouter d’autres étapes. Vous verrez que la liste s’agrandit. Cliquez sur une étape pour modifier son contenu. Pour supprimer une étape, cliquez sur le bouton Supprimer cette étape.
De même, vous pouvez cliquer sur le bouton Dupliquer cette étape pour créer une copie d’une étape existante. Vous pouvez également modifier l’ordre des étapes en utilisant les flèches Déplacer l’étape vers le haut et Déplacer l’étape vers le bas.
Configuration d’une étape de requête
Dans la première étape de votre moniteur, vous remarquerez deux onglets sous la description de l’étape : Requête et Réponse. Dans le cadre du monitoring Multi-step API, une étape est un appel aller-retour à l’API (soit une requête et une réponse). Pour chaque étape, vous pouvez définir votre requête et indiquer à Uptrends comment gérer la réponse. Chaque scénario Multi-step API commence par une étape vide. Nous allons voir ensemble comment la remplir.
Requête
L’onglet Requête contient toutes les données nécessaires à cette étape pour effectuer la requête HTTP. Au minimum :
- Choisissez la méthode HTTP appropriée, soit GET, POST, PUT, PATCH, DELETE, HEAD ou OPTIONS. Si vous avez besoin d’une méthode différente, contactez-nous.
- Renseignez l’URL pour la requête. Utilisez une URL complète, comprenant le protocole (“https://” ou “http://"), le nom de domaine et le chemin d’accès à votre API, ainsi que tout paramètre de chaîne de requête que vous souhaitez inclure.
- Si vous le souhaitez, ajoutez une courte description pour cette étape. Cette description apparaîtra dans les résultats de la vérification du moniteur.
Requête body
Lorsque vous sélectionnez une demande POST, PUT, PATCH, HEAD, OPTIONS ou DELETE, le champ Requête body (Corps de la requête) apparaît. Précisez les données que vous souhaitez envoyer dans le cadre de la requête (très probablement des données JSON, des données XML ou des données de formulaire encodées). Dans la plupart des cas, votre serveur a besoin que vous spécifiiez le format des données que vous envoyez pour pouvoir les lire et les traiter. Pour ce faire, vous devez ajouter une valeur Content-Type dans l’en-tête de requête comme décrit dans le paragraphe suivant.
En-têtes de requête
Une requête HTTP contient généralement des en-têtes de requête (ou request headers) pour spécifier le format des données envoyées ou pour décrire plus en détail le type de réponse attendu. Lorsque vous configurez une étape de requête, vous remarquerez que certains en-têtes sont ajoutés automatiquement. Ces en-têtes sont constitués d’un ensemble d’en-têtes par défaut, en fonction du type de requête que vous effectuez (les demandes GET auront un ensemble d’en-têtes différent de celui des demandes POST, par exemple). Un en-tête par défaut peut être remplacé (à l’exception de l’en-tête Content-Length). Il suffit d’ajouter un nouvel en-tête portant exactement le même nom que l’en-tête existant, mais avec une valeur différente.
De nouveaux en-têtes peuvent également être ajoutés. Par exemple, pour ajouter l’en-tête Content-Type mentionné précédemment, procédez comme suit :
- Cliquez sur le bouton pour ajouter une clé et une valeur d’en-tête de requête.
- Saisissez Content-Type dans le champ Nom.
- La valeur d’en-tête appropriée dépend des données que vous envoyez. Les types de contenu les plus courants sont
application/jsonpour les données JSON,text/xmlpour les données XML, etapplication/x-www-form-urlencodedpour les données de formulaires web.
De même, si votre API exige une authentification, ajoutez un en-tête Authorization avec les données appropriées dans le champ Valeur.
L’image ci-dessus montre un exemple d’étape de requête. Vous remarquerez ce qui suit :
- Il s’agit d’une requête POST vers
https://www.galacticresorts.com/api/Reservation. - Les en-têtes par défaut définis pour cette requête sont les suivants :
HostAccept-EncodingConnectionContent-Length
- Les valeurs des en-têtes
HostetContent-Lengthseront déterminées lors de l’envoi de la requête. - Des en-têtes manuels
Content-TypeetAuthorizationont été ajoutés pour spécifier le format des données et fournir les informations d’identification nécessaires. - L’en-tête par défaut
Connectiona été remplacé. - Le corps de la requête contient du contenu
x-www-form-urlencoded, qui fait référence à certaines variables.
Authentification
De nombreuses API sont protégées et ne sont accessibles qu’en fournissant des informations de connexion. Si votre API utilise l’authentification au niveau du protocole HTTP, choisissez votre type d’authentification (Basic, NTLM ou Digest) et renseignez le nom d’utilisateur et le mot de passe correspondants. Vous pouvez également configurer l’authentification basée sur OAuth en utilisant des étapes distinctes. Cliquez ici pour en savoir plus sur la configuration de l’authentification intégrée ou personnalisée.
Utilisation d’un jeu d’identification de coffre-fort
Il est possible d’utiliser les références d’identification du coffre-fort à tout moment dans le corps de la requête, dans les en-têtes de requête ou en tant que valeur pour votre nom d’utilisateur/mot de passe dans la partie Authentification. Pour faire référence à un élément de coffre-fort, utilisez l’une des deux syntaxes suivantes : {{@VaultItem.<itemGuid>.Password}} ou {{@VaultItem.<itemGuid>.Username}}, selon la valeur requise. Pour trouver le itemGuid, accédez à l’élément du coffre-fort avec vos informations d’identification, puis copiez la dernière partie de l’URL dans la barre d’URL de votre navigateur.
Importation de requêtes cURL
Vous pouvez aussi importer directement des requêtes cURL pour créer vos étapes sans devoir les recréer manuellement. Voici comment faire :
- Dans l’éditeur visuel d’étapes (accessible depuis l’onglet Étapes dans les paramètres du moniteur) du moniteur Multi-step API dans lequel vous souhaitez importer une étape basée sur une commande cURL, cliquez sur le bouton Importation cURL pour ouvrir l’assistant d’importation.
- Cliquez sur le bouton Suivant.
- Copiez la ou les instructions de votre ligne de commande cURL. Par exemple, imaginons que vous vouliez créer une étape basée sur cette instruction cURL :
curl -X POST https://www.galacticresorts.com/api/Reservation -H "Content-Type: application/x-www-form-urlencoded" -u username:password -d "name=Joe&productId=97f8fcc9-11b5-4d86-b208-ccb6d2be35e3&sols=5"
Cette requête permet de créer une réservation sur notre site fictif de réservation de séjours galactiques GalacticResorts.com.
Vous pouvez ajouter plusieurs fonctions d’un coup, en copiant plusieurs commandes cURL.
- Si nécessaire, précisez le format de la commande. Dans la plupart des cas, l’option Détection automatique devrait suffire.
- Cliquez sur le bouton Suivant.
- Dans la dernière étape de l’assistant, cliquez sur le bouton .
Le résultat de la commande cURL présentée dans cet exemple serait le suivant :
Le moniteur Multi-step API ne prend pas en charge toutes les options incluses dans la ligne de commande cURL. Les options non prises en charge sont automatiquement ignorées. Assurez-vous donc d’essayer l’étape pour vérifier que tout fonctionne comme attendu.
Réponse
L’onglet Réponse contient toutes les options permettant d’effectuer des vérifications sur les données de réponse (à l’aide d’assertions) et de traiter ces données en préparation de l’étape suivante (à l’aide de variables).
Assertions
Définir vos étapes et les configurer avec les données correctes est la base d’une bonne configuration. Cependant, il est également important de regarder les résultats de chaque étape. Appeler une série d’URL ne sert à rien si elles ne renvoient pas les bons résultats. Les assertions vous aident à réaliser ces vérifications.
Les assertions sont des vérifications que vous pouvez exécuter pour vérifier que la réponse à une étape particulière se comporte comme prévu, par exemple, en vérifiant son contenu ou en vérifiant qu’elle a été récupérée dans un certain laps de temps. Comme pour les variables, vous spécifiez la source pour la vérification, par exemple, une propriété JSON du corps de réponse JSON, une requête XPath sur le corps de réponse XML, ou même simplement le code d’état de la réponse, sa durée ou la longueur du contenu.
Pour d’autres exemples d’assertions, lisez notre article complet sur la définition des assertions.
Variables
Lorsque vous configurez des scénarios multi-étapes, il est probable qu’au moins une de ces étapes dépendra de certaines données récupérées lors d’une étape précédente. En capturant cette donnée, en la stockant temporairement et en la transmettant aux étapes suivantes, vous créez une progression naturelle d’étapes interconnectées, sans avoir besoin d’écrire de code.
C’est justement pour cela que nous avons prévu les variables. Chaque étape peut créer de nouvelles variables et accéder aux variables créées par d’autres étapes, ce qui permet de réutiliser les données précédemment capturées dans le scénario.
Vous pouvez définir l’origine d’une variable, qui sera probablement une valeur particulière issue de données JSON ou XML, mais la capture d’en-têtes de réponse ou même de données à partir d’une redirection est également possible. Une fois qu’une variable a été définie, vous pouvez l’utiliser n’importe où dans votre configuration multi-étapes simplement en utilisant son nom : {{my-variable}}.
Pour plus d’exemples de variables, lisez l’article sur la définition et l’utilisation de variables.
Nombre maximum de tentatives
Dans certains cas, il se peut que votre API ait besoin d’un certain temps pour traiter une requête entrante avant de pouvoir confirmer la réussite de l’opération. Par exemple, imaginons que vous téléchargiez un fichier en vue de son traitement dans votre API. Pendant son traitement, l’API répond aux requêtes concernant le statut avec {"result":"processing"} dans un corps JSON. Une fois le traitement terminé, l’API répond avec {"result":"success"}. Dans ces cas, vous pouvez configurer le moniteur pour qu’il continue à interroger l’API jusqu’à ce qu’elle confirme une réussite, en utilisant le paramètre Nombre maximal de tentatives.
Cette fonction configurera le moniteur pour qu’il réessaie l’étape si une ou plusieurs des assertions suivantes de l’étape rencontrent un échec : Response body as JSON result Is equal to success pour l’exemple mentionné ci-dessus. Vous pouvez définir le nombre de tentatives que le moniteur doit effectuer, à hauteur d’un maximum de 50 tentatives. Le nombre minimum de tentatives est fixé à deux, et la requête initiale compte comme première tentative.
En plus du nombre de tentatives, vous pouvez définir le temps d’attente entre ces tentatives. Ce temps d’attente doit être compris entre 500 et 3 000 ms. La valeur par défaut est fixée à 1 000 ms.
Pour chaque étape, vous pouvez configurer un nombre maximum de tentatives ainsi qu’un temps d’attente minimum intermédiaire.
Le moniteur continuera à réessayer l’étape jusqu’à ce que le nombre maximal de tentatives soit atteint ou que toutes les assertions réussissent. À ce moment-là, le moniteur continue normalement, en exécutant le reste des étapes dans l’ordre. Si le nombre maximal de tentatives est atteint et qu’au moins une assertion a échoué, le moniteur signale une erreur dans le journal du moniteur.
Le coût du moniteur MSA reste le même, quel que soit le nombre de tentatives.
Configuration des téléchargements de fichiers
Les moniteurs d’API multi-étapes vous permettent d’importer des fichiers depuis votre coffre-fort dans le cadre de l’une de vos étapes de requête. Toute étape HTTP configurée dans le moniteur d’API multi-étapes qui contient un corps de requête peut correspondre à un téléchargement de fichier de données de formulaire (form-data) ou binaires, ou à une simple requête de texte brut. Les fichiers seront envoyés comme du contenu multipart/form-data ou binaire. Pour ajouter un fichier form-data, procédez comme suit :
- Téléchargez le fichier en question dans votre coffre-fort. La taille maximale du fichier est 2 Mo.
- Dans les paramètres de votre moniteur API multi-étapes, ajoutez une étape de requête ou utilisez une étape existante pour exécuter le téléchargement du fichier.
- Dans l’onglet Requête de l’étape qui doit exécuter le téléchargement du fichier, définissez la méthode de requête sur POST, PUT ou PATCH (en fonction de votre cas) et renseignez l’URL de la requête.
- Dans Requête body, sélectionnez l’option Télécharger un fichier (en tant que données de formulaire).
- Cliquez sur le bouton qui s’affiche.
- Choisissez un fichier dans la liste de téléchargement de fichiers du coffre-fort, puis cliquez sur le bouton .
- Il n’est pas nécessaire d’ajouter des en-têtes de requête spécifiques. Nous rajouterons automatiquement un en-tête de requête pour
Content-Lengthet nous définironsContent-Type: multipart/form-dataavec la valeur correcte.
Si vous souhaitez télécharger un fichier sans qu’Uptrends ajoute de métadonnées Content-Disposition au corps de requête, sélectionnez l’option Télécharger un fichier (en tant que binaire) dans la partie Requête body à l’étape 4 ci-dessus. Nous produirons automatiquement les en-têtes répertoriés dans Request headers, sans ajouter ces métadonnées. Cela vous permettra de tester votre API même si celle-ci nécessite un fichier de données binaires brutes.
Il faut savoir que votre API peut s’attendre à une valeur spécifique pour le nom de fichier. La requête inclura un en-tête construit automatiquement Content-Disposition, avec des métadonnées. La valeur de cet en-tête contient un paramètre name. Par défaut, nous utiliserons le nom de fichier que vous avez spécifié dans le coffre-fort. Assurez-vous que le nom de fichier que vous spécifiez lors de l’ajout du fichier au coffre-fort correspond à la valeur attendue par votre API. Par exemple, si votre API s’attend à ce que le fichier téléchargé s’appelle “image”, assurez-vous de spécifier “image” (sans extension de fichier) comme nom de fichier dans l’élément de coffre-fort approprié.
Configuration d’une étape d’attente
Lorsque vous avez une séquence d’étapes de requête dans votre moniteur, chaque étape est exécutée dès que l’étape précédente est terminée, sans aucun délai. Cependant, cette exécution immédiate peut être un peu trop rapide pour certains scénarios.
Imaginons qu’une méthode API demande la génération d’un fichier de rapport. L’API lance un processus de backend pour générer le fichier et demande à l’appelant d’envoyer une deuxième requête afin de télécharger le nouveau fichier. La génération du fichier pouvant prendre une seconde ou deux, l’appelant doit attendre quelques secondes avant d’envoyer la deuxième requête. Si la deuxième requête est envoyée trop tôt, elle échouera car le fichier généré n’est pas encore prêt.
Pour ce scénario, il est important d’attendre avant que la deuxième requête ne soit exécutée. Pour ce faire, vous pouvez insérer une étape d’attente distincte. Ce type d’étape vous permet de spécifier le nombre de millisecondes à attendre. Par exemple, pour attendre 3 secondes, spécifiez 3 000 millisecondes comme temps d’attente. Ce temps d’attente sera inclus dans le temps total pour ce moniteur.
Pour ajouter une étape d’attente, cliquez simplement sur le bouton Ajouter une étape d’attente et spécifiez le nombre de millisecondes à appliquer. Si nécessaire, vous pouvez déplacer l’étape d’attente au bon endroit de votre scénario à l’aide des boutons Déplacer l’étape vers le haut/bas.
Le temps d’attente pour une étape d’attente est limité à 60 secondes : une étape d’attente n’est pas destinée à surveiller une tâche de longue durée prenant plusieurs minutes ou heures. Si le moniteur dépasse le temps total maximal d’exécution, la vérification s’arrête et un échec est signalé.
Ajouter une étape d’attente à votre moniteur ne vous coûte rien. Le coût d’un moniteur API multi-étapes est uniquement basé sur le nombre d’étapes de requêtes.
Résultats, erreurs et alertes du monitoring multi-étapes
Les moniteurs API multi-étapes se comportent de la même manière que tous les autres moniteurs. Chaque vérification apparaît dans le journal du moniteur et fournit des informations détaillées pour chaque étape. Pour chaque étape, cette information comprend :
- la durée totale de l’étape (en millisecondes)
- l'URL qui a été interrogée au cours de cette étape
- le code d’état HTTP qui a été renvoyé
- le résultat pour chaque assertion (réussite ou échec)
- les en-têtes et le contenu des requêtes que nous avons envoyés
- les en-têtes et le contenu de la réponse que nous avons reçus
Si un problème se produit au cours de l’une des étapes ou si l’une des assertions que vous avez définies ne réussit pas, le moniteur échouera et signalera une erreur. Comme toujours, ces erreurs peuvent générer des alertes en fonction de vos définitions d’alertes.