Requête API

Principe technique

Requête API s'appuie sur la plateforme logicielle Node.js, elle-même construite sur le moteur open-source JavaScript V8. Ces technologies vous garantissent l'exécution de vos requêtes API avec un haut niveau de performance et de parallélisation.

Configuration de l'URL

La première étape dans requête API est de renseigner une URL.

Pour faciliter la lecture, la modification et la saisie, l'URL est décomposée et ses données sont organisées dans différentes sections. Vous pouvez l'éditer depuis les sections ou directement dans le champs URL, toute modification est propagée pour conserver la cohérence des données de l'ensemble (données réactives).

Paramètres

Spécifiez vos paramètres de requête en renseignant un couple clé/valeur.

Entêtes

L'ajout d'entêtes personnalisées peut être nécessaire pour vos besoins spécifiques, comme pour spéficier le Content-Type du corps de requête ou le User-Agent du client.

🚀 Certains champs sont activement traités par nos serveurs pour appliquer le paramétrage. C'est le cas de l'entête Accept-Encoding qui active la décompression gzip du contenu de la réponse.

Authentification

Il existe plusieurs méthodes d'authentification auprès d'un serveur HTTP pour accéder aux ressources. Certaines demandent un nom d'utilisateur et un mot de passe. D'autres, plus complexes, appliquent des algorithmes de vérification et de hachage pour une plus grande sécurité.

Vivlab prend en compte les méthodes d'authentification les plus connues pour vous faciliter le paramétrage.

Basic

La méthode d'authentification Basic est la plus simple. Elle transmet le nom de l'utilisateur et le mot de passe séparés par le caractère « : » et encodés sur Base64.

Pour configurer l'authentification Basic, vous pouvez renseigner les champs suivants :

  • Utilisateur
  • Mot de passe

Vivlab se chargera automatiquement d'encoder vos paramètres sur Base64 et de créer l'entête Authorization: Basic <Utilisateur:Mot de passe>

Digest

La méthode d'authentification Digest transmet le nom de l'utilisateur et du mot de passe en appliquant l'algorithme de hachage MD5/MD5-sess.

Pour configurer l'authentification Digest, vous devez renseigner les champs suivants :

  • Utilisateur
  • Mot de passe

Vivlab se chargera automatiquement de négocier avec le serveur pour envoyer vos paramètres d'authentification avec l'algorithme de hachage qui correspond.

Bearer

La méthode d'authentification Bearer permet de sécuriser les échanges client-serveur par validation de jeton (voir détail rfc7519).

Pour configurer l'authentification Bearer, saisissez directement le jeton dans le champs suivant :

  • Token

Vivlab se chargera automatiquement de générer l'entête Authorization: Bearer <Token>.

Hawk

La méthode d'authentification Hawk fonctionne avec l'algorithme HMAC.

Pour configurer l'authentification Hawk, vous devez renseigner les champs suivants :

  • ID
  • Clé
  • Algorithme — généralement sha256 ou hmac sha256

Vivlab se chargera automatiquement de résoudre le challenge envoyé par le serveur, avec vos paramètres Hawk.

Aws

Aws est la méthode d'authentification pour Amazon Web Service, exploitant la Signature Version 4. La plupart des demandes de AWS doivent être signées avec une clé d'accès, qui consiste en un ID de clé d'accès et une clé d'accès secrète.

Pour configurer l'authentification Aws, vous pouvez renseigner les champs suivants :

  • Key
  • Secret
  • Session
  • Bucket
  • Service

Pour plus d'informations, consultez la documentation AWS.

Corps de requête

Le corps de requête permet d'attacher à la requête les données à transmettre. Vous pouvez transmettre des données brutes ou un formulaire.

Brut

Le mode brut peut contenir ce que vous voulez. Non pré-traitées, les données sont envoyées telles quelles, à l'exception du remplacement des variables d'environnement.

Vous devez manuellement définir l'entête Content-Type de votre requête pour spécifier le type de données que le serveur API devra interpréter.

Pour faciliter la lecture et la saisie des données brutes, vous pouvez sélectionner un affichage (JSON, HTML) pour formater votre type de données.

Vous pouvez également passer en mode plein écran en cliquant sur l'icône fullscreen et faire des retours à la ligne en cliquant sur l'icône menu.

Form

Le mode Form permet de transférer des données de formulaire, en spécifiant les couples de clé/valeur.

Vous devez manuellement définir l'entête Content-Type de votre requête si vous souhaitez envoyer en application/x-www-form-urlencoded ou multipart/form-data.

Le traitement des données Form s'effectue en fonction du Content-Type que vous aurez spécifié dans l'entête.

🥀 Le transfert des données binaires comme les médias images, audios et vidéos n'est actuellement pas supporté.

Temps de réponse

Le temps de réponse correspond à la durée entre l'émission de la requête et la réception de la réponse. Les différentes phases du temps de réponse sont également disponibles pour vous aider à mieux diagnostiquer les problèmes potentiels de vos infrastructures.

Le temps de réponse comprend 5 phases :

  • Initialisation du Socket
  • Résolution DNS
  • Établissement TCP
  • Réception du 1er paquet — Temps de la réponse du serveur (TTFB)
  • Réception de tous les paquets

Tests

Status code

Le status code HTTP (défini dans la RFC2616) permet de connaître l'état de la réponse traitée par le serveur grâce à un code à 3 digits (nombre allant de 1xx à 5xx).

Vous pouvez vérifier la valeur du status code reçu.

  • Comparaison — Égale / différente / supérieure / inférieure
  • Attendue — Nombre à comparer

Si vous activez la fonction "Alerte" et ne souhaitez pas recevoir d'alerte quand un code erreur HTTP spécifique est détecté, créez un test avec ce code erreur, comme dans l'exemple ci-dessous.

Taille du contenu

La taille du contenu est exprimée en octet et correspond au poids de la réponse (décompressée si gzip détecté) calculé sur encodage utf8.

La valeur ne s'appuie pas sur l'entête Content-Length car elle peut être omise dans la réponse. Ajoutez un test Entête si la valeur diffère et que vous souhaitez tester à partir de ce champs.

  • Comparaison — Égale / différente / supérieure / inférieure
  • Attendue — Nombre à comparer exprimé en octect
Entête

Les entêtes HTTP permettent au serveur de transmettre des informations supplémentaires, en plus du contenu de la réponse.

Vous pouvez tester la valeur d'un champs en spécifiant la clé.

  • Propriété — Nom de la clé (casse insensible)
  • Comparaison — Égale / différente / supérieure / inférieure
  • Attendue — Valeur de la clé (casse sensible)
Corps HTML

Pour extraire les données d'une réponse HTML, vous devez spécifier le chemin XPath dans le champs Propriété. Vivlab a implémenté le module wgxpath comme langage de demande HTML.

3 champs sont requis pour le test :

  • Propriété — Chemin XPath (casse sensible)
  • Comparaison — Égale / différente / supérieure / inférieure
  • Attendue — Valeur à tester (casse sensible)

Les spécifications du XPath sont normalisées par la W3C.

Le chemin du XPath est nécessaire à la récupération de la valeur à tester. Il peut être facilement récupéré depuis un navigateur avec l'outil d'inspection.

La procédure fonctionne sur la plupart des navigateurs :

  1. Cliquez droit sur l'élement à tester de la page web.
  2. Sélectionnez Inspecter ou Examiner l'élement, la fenêtre d'inspection apparaît.
  3. Dans la fenêtre d'inspection, cliquez droit sur l'élément surligné.
  4. Sélectionner Copier -> Copier XPath.
  5. Vous avez à présent le XPath dans le presse-papier, prêt à être collé.

Cette méthode fonctionne aussi sur le format XML pour récuperer le XPath.

Ci-dessous un exemple de test appliqué à la page Wikipedia :

1 - Configuration du test
Vérifier que la valeur XPath //*[@id="n-randompage"]/a contient Article
2 - Résultat obtenu
La valeur Article au hasard est extraite du XPath et contient bien Article
Réponse JSON

Pour extraire les données de réponse JSON, vous devez spécifier le chemin dans le champs Propriété. Vivlab a implémenté le module JMESPath comme langage de demande JSON. Le format JSON est normalisé dans la RFC8259.

3 champs sont requis pour le test :

  • Propriété — Chemin JSON (casse sensible)
  • Comparaison — Égale / différente / supérieure / inférieure
  • Attendue — Valeur à tester (casse sensible)

Dans nos exemples, nous allons nous appuyer sur les données JSON de livres ci-dessous :

{
  "collection": "books",
  "section": "3rd floor",
  "list": [
    {
      "title": "Tom Sawyer",
      "author": "Twain, Mark",
      "year_written": 1862,
      "edition": "Random House",
      "price": 7.75
    },
    {
      "title": "Harry Potter",
      "author": "Rowling, J.K.",
      "year_written": 2000,
      "edition": "Harcourt Brace",
      "price": 19.95
    },
    {
      "title": "Lord of the Rings",
      "author": "Tolkien, J.R.",
      "year_written": 1937,
      "edition": "Penguin",
      "price": 27.45
    }
  ]
}
Chemin JSON
Valeur récupérée
collection
books
section
3rd floor
list[0].title
Tom Sawyer
list[0].author
Twain, Mark
list[2].title
Lord of the Rings
list[2].author
Tolkien, J.R.

Vous pouvez étendre les possibilités, comme rechercher ou filtrer une valeur, en consultant d'autres exemples dans la documentation de JMESPath.

Temps de réponse

Vous pouvez tester chacune des 5 phases du temps de réponse.

  • Comparaison — Égale / différente / supérieure / inférieure
  • Attendue — Nombre à comparer exprimé en millisecondes

Limitations

Notre plateforme a été conçue pour être très performante et peut traiter plusieurs exécutions en parallèle. Toutefois nous avons mis en place des limitations pour éviter certains problèmes et vous les remonter :

  • Vos requêtes n'aboutissent pas et engendre un temps d'attente sans raison.
  • Les boucles de redirection surchargent et spamment inutilement notre plateforme.
  • Un script bloque involontairement une exécution.

Le temps d'exécution d'une requête est limité à 6 secondes. Ce temps est généralement largement suffisant pour exécuter la requête et ses tests.