Come utilizzare l’API winadmin.it con client PHP

di

Esplorando Diversi Client PHP per l’API winadmin.it

In questa guida approfondiremo le varie opzioni di client PHP disponibili per interagire con l’API di winadmin.it.

Analizzeremo in dettaglio l’impiego dell’API winadmin.it attraverso funzioni come file_get_contents, l’utilizzo di Guzzle, HTTPful, e il client HTTPS di Symfony.

Cos’è l’API winadmin.it?

winadmin.it offre una suite di strumenti gratuiti ideali per monitorare le prestazioni di un sito web. Tra questi strumenti figurano un analizzatore di link rotti, un misuratore del tempo di caricamento e un verificatore DNS. L’accesso a questi strumenti è possibile sia tramite l’interfaccia web, sia attraverso la loro API dedicata.

L’API si basa su protocollo HTTP ed è quindi accessibile da qualsiasi linguaggio di programmazione dotato di una libreria client HTTP. L’API prevede un livello gratuito particolarmente generoso, che consente di iniziare a utilizzarla senza l’obbligo di fornire dati di pagamento.

Obiettivi del Tutorial

Lo scopo di questo tutorial è la creazione di uno script, eseguibile da terminale, che calcoli il tempo di caricamento del sito web di Google, visualizzando tale valore a schermo. Realizzeremo questo programma di esempio usando diversi client HTTP PHP, mostrando così come si presenta l’interazione con l’API.

Nello specifico, utilizzeremo sia le funzioni native di PHP – file_get_contents() e php_curl – sia l’estensione Guzzle PHP. Nonostante la semplicità degli esempi, essi illustreranno i concetti fondamentali alla base dell’uso dell’API winadmin.it.

Requisiti Preliminari

Per seguire questo tutorial, è indispensabile avere una conoscenza pregressa di PHP e averlo installato sul proprio sistema. Inoltre, sarà necessario Composer per la gestione delle dipendenze.

È inoltre raccomandato l’utilizzo di un editor di testo per la stesura del codice. L’autore utilizzerà Visual Studio Code, un editor open source di Microsoft, scaricabile dal sito ufficiale.

Panoramica sull’API di winadmin.it

L’API winadmin.it presenta vari endpoint a seconda dell’azione desiderata. La lista completa degli endpoint, unitamente alla documentazione, è consultabile nella pagina di documentazione dedicata.

Creazione di un Account winadmin.it

Per iniziare a utilizzare l’API, occorre creare un account attraverso la pagina di registrazione. Al termine della registrazione, si verrà reindirizzati alla dashboard, dove si troverà la propria chiave API. L’aspetto della dashboard dovrebbe essere simile all’immagine qui sotto. Si precisa che l’autore ha oscurato la propria chiave API per ragioni di sicurezza.

Ogni richiesta API dovrà includere questa chiave come intestazione. Vedremo tra poco come implementare questo aspetto.

Con un account winadmin.it e PHP installato, siamo pronti per cominciare la realizzazione del progetto.

Struttura del Progetto

Iniziamo con la creazione di una cartella in cui andremo a salvare i file del progetto. Successivamente, creiamo questi file:

  • .env
  • con_ricciolo.php
  • con_file_get_contents.php
  • con_guzzle.php

Quindi, eseguiamo il seguente comando per installare le dipendenze vlucas/phpdotenv e guzzlehttp/guzzle:

composer require vlucas/phpdotenv guzzlehttp/guzzle

A questo punto, la struttura della cartella del progetto dovrebbe presentarsi come segue:

Apriamo il file .env e inseriamo la seguente riga di codice, sostituendo <your-api-key> con la chiave API ottenuta dalla dashboard di winadmin.it:

API_KEY=<your-api-key>

Utilizzo della Funzione file_get_contents()

Un primo approccio per effettuare richieste HTTP consiste nell’uso della funzione nativa di PHP file_get_contents(). La firma di tale funzione è la seguente:

file_get_contents(path, include_path, context)

Sebbene questa funzione sia spesso impiegata per la lettura di file locali, è possibile utilizzarla anche per leggere risorse web, come ad esempio i dati restituiti da un endpoint API.

Per iniziare, apriamo il file with_file_get_contents.php e aggiungiamo la struttura standard di PHP.

<?php
   // il codice verrà inserito qui
?>

Aggiungiamo ora le righe necessarie per caricare le dipendenze:

require_once('vendor/autoload.php');

Successivamente, carichiamo le variabili d’ambiente, inclusa la chiave API:

$dotenv = DotenvDotenv::createImmutable(__DIR__);
$dotenv->load();

Definiamo quindi il payload, ovvero i dati che invieremo nel corpo della richiesta:

$payload = json_encode([
    "url" => "https://www.google.com",
    "proxyCountry" => "us",
    "followRedirect" => true
]);

Abbiamo creato la variabile $payload assegnandole una stringa JSON contenente url, proxyCountry e followRedirect come proprietà.

La proprietà url specifica la pagina web di cui vogliamo misurare il tempo di caricamento.

proxyCountry è la posizione del server che useremo per effettuare la richiesta. In questo esempio utilizziamo il server USA, ma sono disponibili anche India, Cina, Regno Unito e Francia (si rimanda alla documentazione per maggiori dettagli).

Infine, followRedirect indica se il server proxy deve seguire eventuali redirect, misurando il tempo di risposta finale, oppure del primo redirect.

A questo punto, creiamo un array di $options per configurare la nostra richiesta:

$options = [
    "http" => [
        "method" => "POST",
        "header" => array("Content-Type: application/json", "x-api-key : " . $_ENV['API_KEY']),
        "content" => $payload
    ]
];

In questo oggetto options abbiamo specificato che il metodo HTTP è POST, e abbiamo incluso un’intestazione che specifica Content-Type (JSON) e la x-api-key prelevata dalle variabili d’ambiente.

Ora creiamo un flusso di dati che conterrà le nostre opzioni:

$context = stream_context_create($options);

Effettuiamo la richiesta utilizzando la funzione file_get_contents() e memorizziamo la risposta:

$response = file_get_contents("https://api.winadmin.it.com/loadtime", false, $context);

Abbiamo inviato la richiesta all’endpoint https://api.winadmin.it.com/loadtime. Il valore false indica a PHP di non usare il percorso. L’ultimo parametro è il contesto creato precedentemente.

Per visualizzare la risposta, utilizziamo il seguente output:

echo "Loadtime: " . json_decode($response)->data->total . "n";

Il file completo avrà questo aspetto:

<?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.winadmin.it.com/loadtime", false, $context);

    echo "Loadtime: " . json_decode($response)->data->total . "n";
?>

Eseguendo il file tramite il comando:

php with_file_get_contents.php

Otterremo un output simile a questo:

Loadtime: 81

Utilizzo di cURL

cURL è uno strumento a riga di comando che permette di effettuare richieste URL lato client. In PHP, possiamo utilizzarlo tramite l’estensione php-curl. Per iniziare, apriamo il file with_curl.php e inseriamo la base del codice PHP:

<?php
    // tutto il nuovo codice sarà inserito qui
?>

Importiamo le dipendenze e carichiamo la variabile d’ambiente API_KEY, definita nel file .env:

require_once('vendor/autoload.php');

$dotenv = DotenvDotenv::createImmutable(__DIR__);
$dotenv->load();

Creiamo una variabile per memorizzare le intestazioni come array. Ogni elemento dell’array sarà una specifica intestazione:

$header = ["Content-type: application/json", "x-api-key: " . $_ENV['API_KEY']];

Abbiamo definito due intestazioni: una per il tipo di contenuto e una per la chiave API.

Definiamo il corpo della richiesta:

$body = json_encode([
    "url" => "google.com",
    "proxyCountry" => "us",
    "followRedirect" => true
]);

A questo punto, creiamo una sessione curl con la funzione curl_init(), passando l’URL di destinazione come argomento:

$ch = curl_init("https://api.winadmin.it.com/loadtime");

Definiamo le opzioni per la sessione, includendo intestazione e corpo della richiesta, usando curl_setopt_array():

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => $header,
    CURLOPT_POSTFIELDS => $body
]);

Effettuiamo la richiesta usando curl_exec():

$response = curl_exec($ch);

La risposta è stata memorizzata nella variabile $response. Chiudiamo la sessione per liberare le risorse:

curl_close($ch);

Stampiamo la risposta a schermo:

var_dump($response);

Il file finale avrà questo aspetto:

<?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.winadmin.it.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);
?>

Eseguendo lo script con php with_curl.php, dovremmo ottenere un output simile:

{"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 richiesta è stata eseguita con successo e l’API ha risposto con i dati JSON. Questi dati possono essere utilizzati in modo appropriato.

Utilizzo di Guzzle

Nell’ultima parte del tutorial, useremo Guzzle per realizzare lo script. Come di consueto, inseriamo la base del codice PHP all’interno del file with_guzzle.php:

<?php
    // tutto il codice sarà inserito qui
?>

Importiamo le dipendenze, ovvero Guzzle Client e Request Objects, e carichiamo le variabili d’ambiente:

require_once('vendor/autoload.php');

use GuzzleHttpClient;
use GuzzleHttpPsr7Request;

Carichiamo le variabili d’ambiente:

$dotenv = DotenvDotenv::createImmutable(__DIR__);
$dotenv->load();

Creiamo un’istanza del client HTTP di Guzzle:

$client = new GuzzleHttpClient();

Definiamo le intestazioni per la richiesta:

$headers = [
    'x-api-key' => $_ENV['API_KEY'],
    'Content-Type' => 'application/json'
];

Definiamo il corpo della richiesta:

$body = json_encode([
    "url" => "google.com",
    "proxyCountry" => "us",
    "followRedirect" => true
]);

Ora effettuiamo la richiesta, istanziando la classe Request e passando URL, intestazione e corpo dell’endpoint API:

$request = new Request('POST', 'https://api.winadmin.it.com/loadtime', $headers, $body);

Invia la richiesta:

$response = $client->sendAsync($request)->wait();

Otteniamo il corpo della risposta:

$response_body = $response->getBody();

Infine, decodifichiamo la risposta JSON e stampiamo il tempo di caricamento:

echo "Loadtime: " . json_decode($response_body)->data->total . "n";

Il file completo avrà questo aspetto:

<?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.winadmin.it.com/loadtime', $headers, $body);

    $response = $client->sendAsync($request)->wait();

    $response_body = $response->getBody();

    echo "Loadtime: " . json_decode($response_body)->data->total . "n";
?>

Eseguendo lo script con il comando:

$php with_guzzle.php

Vedremo una risposta simile a:

Loadtime: 130

Conclusioni

In questo articolo abbiamo analizzato i diversi client che possono essere utilizzati durante la creazione di un progetto PHP che interagisce con l’API di winadmin.it.

Mentre gli script presentati in questo progetto utilizzano la riga di comando come principale mezzo di output, in scenari reali è più comune visualizzare la risposta su una pagina web o scriverla su un file. Gli script dimostrativi erano di natura semplice, ma hanno lo scopo di illustrare i concetti fondamentali relativi all’uso dell’API winadmin.it. Per interagire con API diverse, è sufficiente modificare l’endpoint e passare opzioni diverse nel corpo della richiesta.

Potrebbe interessarti anche l’articolo su come utilizzare l’API di ricerca DNS di winadmin.it in Javascript.