Comment utiliser l'API toptips.fr avec les clients PHP
Exploration des Clients PHP pour l'API toptips.fr
Ce guide détaille les différentes méthodes que vous pouvez employer avec PHP pour interagir avec l'API de toptips.fr. Nous allons examiner comment utiliser l'API toptips.fr en exploitant des outils tels que la fonction file_get_contents, la bibliothèque Guzzle, HTTPful, ainsi que le client HTTPS de Symfony.
Qu'est-ce que l'API toptips.fr ?
toptips.fr met à disposition un ensemble d'outils gratuits conçus pour le suivi des performances de votre site web. Ces outils comprennent un analyseur de liens cassés, un test de temps de chargement et un vérificateur DNS. L'accès à ces outils est possible via une interface web ou par le biais de l'API. L'API, basée sur HTTP, est accessible depuis tout langage de programmation doté d'une bibliothèque cliente HTTP. Elle propose un niveau d'utilisation gratuit et généreux, sans nécessité de fournir des informations de paiement pour commencer.
Objectif du guide
Nous allons développer un script, exécutable en ligne de commande, qui mesurera le temps de chargement du site web de Google et affichera le résultat dans le terminal. Nous réaliserons ce programme simple en employant divers clients HTTP PHP, illustrant ainsi les différentes manières d'interagir avec l'API. Nous allons notamment utiliser la fonction native file_get_contents(), l'extension php_curl, et la librairie Guzzle. Ces exemples, bien que basiques, permettront de comprendre les principes fondamentaux de l'utilisation de l'API toptips.fr.
Prérequis
Pour suivre ce tutoriel, une connaissance préalable de PHP ainsi que son installation sur votre ordinateur sont nécessaires. De plus, l'utilisation de Composer est requise pour la gestion des dépendances. Un éditeur de texte sera également indispensable pour la rédaction du code. Pour ma part, j'utiliserai Visual Studio Code, l'éditeur de code open source populaire de Microsoft, disponible en téléchargement sur son site officiel.
Présentation générale de l'API toptips.fr
L'API toptips.fr offre plusieurs points de terminaison (endpoints) en fonction des actions souhaitées. Une liste complète de ces endpoints, ainsi que leur documentation, est disponible sur la page de documentation dédiée.
Création d'un compte toptips.fr
Avant de pouvoir utiliser l'API, vous devrez créer un compte. Pour cela, rendez-vous sur la page d'accueil de l'API et cliquez sur le bouton d'inscription. Une fois l'inscription terminée, vous serez dirigé vers le tableau de bord où votre clé API sera affichée. Le tableau de bord ressemble à l'image ci-dessous, mais pour des raisons de sécurité, ma clé API a été masquée. Cette clé API devra être incluse comme en-tête dans chacune de vos requêtes à l'API. Nous allons voir comment procéder.
Avec votre compte toptips.fr créé et PHP installé, nous pouvons débuter la mise en place de notre projet.
Création du répertoire du projet
Commencez par créer un dossier où seront stockés les fichiers de votre projet. Ensuite, créez les fichiers suivants à l'intérieur :
- .env
- with_curl.php
- with_file_get_contents.php
- with_guzzle.php
Puis, exécutez la commande suivante pour installer les dépendances nécessaires :
composer require vlucas/phpdotenv guzzlehttp/guzzle
À cette étape, la structure de votre projet devrait être la suivante :
Ouvrez maintenant le fichier .env et ajoutez-y la ligne de code ci-dessous, en remplaçant <your-api-key> par votre véritable clé API obtenue depuis le tableau de bord toptips.fr :
API_KEY=<your-api-key>
Utilisation de file_get_contents()
La première méthode que nous allons explorer pour envoyer des requêtes HTTP est l'utilisation de la fonction file_get_contents(), intégrée à PHP. La signature de cette fonction est la suivante :
file_get_contents(path, include_path, context)
Bien que cette fonction soit principalement utilisée pour lire le contenu de fichiers locaux, elle peut aussi être employée pour lire des ressources web, telles que les données retournées par un point de terminaison d'API.
Pour débuter, ouvrez le fichier with_file_get_contents.php et ajoutez-y la structure de base d'un fichier PHP :
<?php // Le code sera inséré ici ?>
Ensuite, nous pouvons commencer par charger les dépendances. Ajoutez la ligne de code suivante à votre fichier :
require_once('vendor/autoload.php');
Puis, chargeons nos variables d'environnement, incluant la clé API :
$dotenv = DotenvDotenv::createImmutable(__DIR__); $dotenv->load();
Ensuite, définissons la charge utile (payload). Il s'agit des données que nous allons envoyer dans le corps de la requête :
$payload = json_encode([
"url" => "https://www.google.com",
"proxyCountry" => "us",
"followRedirect" => true
]);
Nous avons créé une variable $payload à laquelle nous avons affecté une chaîne JSON contenant l'url, le pays du proxy, et l'option de suivi de redirection.
La propriété url indique l'adresse de la page web dont nous voulons vérifier le temps de chargement.
La propriété proxyCountry définit l'emplacement du serveur que nous utiliserons pour envoyer la requête. Dans ce cas, nous utilisons un serveur américain, mais vous pouvez choisir entre l'Inde, la Chine, le Royaume-Uni et la France. Consultez la documentation pour plus d'informations.
La propriété followRedirect détermine si le serveur proxy doit suivre les redirections et mesurer le temps de réponse de la réponse finale ou de la première redirection.
Par la suite, nous allons configurer les options de la requête en ajoutant le code suivant :
$options = [
"http" => [
"method" => "POST",
"header" => array("Content-Type: application/json", "x-api-key : " . $_ENV['API_KEY']),
"content" => $payload
]
];
Nous avons ainsi créé un objet d'options spécifiant que la méthode HTTP utilisée est POST. Nous avons également défini un en-tête avec deux propriétés : le type de contenu en JSON, et la clé API que nous avons récupérée depuis le fichier .env et qui est chargée en tant que variable d'environnement.
Nous pouvons maintenant effectuer la requête en créant un flux auquel nous allons appliquer nos options :
$context = stream_context_create($options);
Puis, nous allons utiliser la fonction file_get_contents() pour envoyer la requête et stocker la réponse dans une variable :
$response = file_get_contents("https://api.toptips.fr.com/loadtime", false, $context);
Nous envoyons la requête à l'adresse https://api.toptips.fr.com/loadtime. Le paramètre false indique à PHP de ne pas utiliser le chemin. Nous passons également le contexte que nous venons de créer.
Pour afficher la réponse, nous allons utiliser la sortie comme suit :
echo "Loadtime: " . json_decode($response)->data->total . "n";
À ce stade, votre fichier devrait ressembler à ceci :
<?php
require_once('vendor/autoload.php');
$dotenv = DotenvDotenv::createImmutable(__DIR__);
$dotenv->load();
$payload = json_encode([
"url" => "https://www.google.com",
"proxyCountry" => "us",
"followRedirect" => true
]);
$options = [
"http" => [
"method" => "POST",
"header" => array("Content-Type: application/json", "x-api-key : " . $_ENV['API_KEY']),
"content" => $payload
]
];
$context = stream_context_create($options);
$response = file_get_contents("https://api.toptips.fr.com/loadtime", false, $context);
echo "Loadtime: " . json_decode($response)->data->total . "n";
?>
En exécutant le fichier avec la commande suivante :
php with_file_get_contents.php
Vous obtiendrez le résultat suivant :
Loadtime: 81
Utilisation de cURL
cURL est un outil en ligne de commande utilisé pour effectuer des requêtes d'URL côté client. En PHP, il est accessible via l'extension php-curl. Pour commencer, ouvrez le fichier with_curl.php et insérez le code PHP de base :
<?php
// Le code sera écrit ici
?>
Ensuite, importons les dépendances et chargeons la variable d'environnement API_KEY définie dans le fichier .env :
require_once('vendor/autoload.php');
$dotenv = DotenvDotenv::createImmutable(__DIR__);
$dotenv->load();
Nous allons ensuite créer un tableau qui contiendra les en-têtes de notre requête :
$header = ["Content-type: application/json", "x-api-key: " . $_ENV['API_KEY']];
Nous avons défini deux en-têtes : un pour le type de contenu et un pour la clé API.
Puis, nous allons définir le corps de la requête :
$body = json_encode([
"url" => "google.com",
"proxyCountry" => "us",
"followRedirect" => true
]);
Après cela, nous allons initialiser une session cURL en utilisant la fonction curl_init(). Nous allons passer en argument l'URL à laquelle nous souhaitons envoyer la requête :
$ch = curl_init("https://api.toptips.fr.com/loadtime");
Nous pouvons maintenant tout rassembler en définissant l'en-tête et le corps comme options pour la session. Pour cela, nous utilisons la fonction curl_setopt_array() :
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => $header,
CURLOPT_POSTFIELDS => $body
]);
Pour envoyer la requête, nous allons utiliser la fonction curl_exec() :
$response = curl_exec($ch);
La réponse est stockée dans la variable $response. Nous allons ensuite fermer la session pour libérer les ressources système utilisées :
curl_close($ch);
Enfin, nous pouvons afficher la réponse à l'écran en utilisant var_dump :
var_dump($response);
Au final, votre fichier de script devrait ressembler à ceci :
<?php
require_once('vendor/autoload.php');
$dotenv = DotenvDotenv::createImmutable(__DIR__);
$dotenv->load();
$header = ["Content-type: application/json", "x-api-key: " . $_ENV['API_KEY']];
$body = json_encode([
"url" => "google.com",
"proxyCountry" => "us",
"followRedirect" => true
]);
$ch = curl_init("https://api.toptips.fr.com/loadtime");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => $header,
CURLOPT_POSTFIELDS => $body
]);
$response = curl_exec($ch);
curl_close($ch);
var_dump($response);
?>
Lorsque nous exécutons le script avec la commande php with_curl.php, vous devriez obtenir le résultat suivant :
{"timestamp":1666083632547,"apiStatus":"success","apiCode":200,"meta":{"url":"google.com","followRedirect":true,"redirectedURL":"https://www.google.com/?gws_rd=ssl","test":{"id":"d20h1hb409qbfwm0g534l51asugpi5hl"}},"data":{"dns":12,"connect":17,"tls":6,"send":21,"wait":110,"total":114}}bool(true)
La requête s'est terminée avec succès et l'API a renvoyé des données JSON. Vous pouvez utiliser ces données selon vos besoins.
Utilisation de Guzzle
Dans la dernière partie de ce tutoriel, nous allons utiliser Guzzle pour écrire le script. Comme toujours, nous allons commencer par insérer le code PHP de base dans le fichier with_guzzle.php :
<?php
// Le code sera inséré ici
?>
Ensuite, importons les dépendances, les objets Guzzle Client et Request, et chargeons les variables d'environnement :
require_once('vendor/autoload.php');
use GuzzleHttpClient;
use GuzzleHttpPsr7Request;
Puis, chargeons les variables d'environnement :
$dotenv = DotenvDotenv::createImmutable(__DIR__); $dotenv->load();
Instancions ensuite un client HTTP Guzzle :
$client = new GuzzleHttpClient();
Puis, préparons les en-têtes pour notre requête :
$headers = [
'x-api-key' => $_ENV['API_KEY'],
'Content-Type' => 'application/json'
];
Définissons ensuite le corps de la requête :
$body = json_encode([
"url" => "google.com",
"proxyCountry" => "us",
"followRedirect" => true
]);
Nous pouvons maintenant envoyer la requête en instanciant la classe Request et en passant l'URL, les en-têtes, et le corps du point de terminaison de l'API :
$request = new Request('POST', 'https://api.toptips.fr.com/loadtime', $headers, $body);
Envoyons maintenant la requête en ajoutant la ligne de code suivante :
$response = $client->sendAsync($request)->wait();
Une fois la requête envoyée, nous pouvons récupérer le corps de la réponse comme ceci :
$response_body = $response->getBody();
Finalement, nous décodons la réponse JSON et affichons le temps de chargement :
echo "Loadtime: " . json_decode($response_body)->data->total . "n";
En résumé, votre fichier devrait ressembler à ceci :
<?php
require_once('vendor/autoload.php');
use GuzzleHttpClient;
use GuzzleHttpPsr7Request;
$dotenv = DotenvDotenv::createImmutable(__DIR__);
$dotenv->load();
$client = new GuzzleHttpClient();
$headers = [
'x-api-key' => $_ENV['API_KEY'],
'Content-Type' => 'application/json'
];
$body = json_encode([
"url" => "google.com",
"proxyCountry" => "us",
"followRedirect" => true
]);
$request = new Request('POST', 'https://api.toptips.fr.com/loadtime', $headers, $body);
$response = $client->sendAsync($request)->wait();
$response_body = $response->getBody();
echo "Loadtime: " . json_decode($response_body)->data->total . "n";
?>
Et si vous exécutez le script avec la commande suivante :
$php with_guzzle.php
Vous verrez la réponse suivante :
Loadtime: 130
Conclusion
Dans cet article, nous avons exploré les différents clients PHP que vous pouvez utiliser lors de la création d'un projet PHP interagissant avec l'API toptips.fr. Bien que les scripts de ce projet utilisent la ligne de commande comme principale forme de sortie, dans des projets réels, la réponse pourrait être affichée sur une page web ou enregistrée dans un fichier. Les exemples de scripts présentés ici sont simples, mais ils illustrent les concepts de base de l'utilisation de l'API toptips.fr. Pour interagir avec d'autres API, vous pouvez modifier le point de terminaison et adapter les options transmises dans le corps de la requête.
Vous pourriez également être intéressé par l'utilisation de l'API de recherche DNS toptips.fr en Javascript.