Nella prima parte di questa guida abbiamo dato un’occhiata alla HTTP API in generale. Abbiamo visto cos’è l’HTTP, abbiamo parlato della struttura delle richieste e delle risposte HTTP e di come i tipi di azione e gli URL si uniscono per determinare quello che si riceve a seguito della richiesta. In questo post daremo un’occhiata all’API HTTP di WordPress.

La HTTP API di WordPress

Dalla versione 2.7 circa, WordPress dispone di un’API per la gestione di HTTP. È composta da 9 funzioni, di cui probabilmente ne userete solo un paio. Le funzioni possono essere suddivise in due gruppi distinti – uno per fare richieste, uno per leggere i risultati.

wp_remote_get(), wp_remote_post(), wp_remote_head() utilizzano rispettivamente i metodi GET, POST e HEAD per richiedere dati da un dato URL. La funzione wp_remote_request() è una funzione generale che permette di specificare un URL e un metodo che lo accompagna.

Anche le funzioni utilizzate per leggere le risposte si spiegano da sole. wp_remote_retrieve_body() ottiene il corpo della risposta, la funzione wp_remote_retrieve_header() ottiene un header denominato. La funzione wp_remote_retrieve_headers() restituisce tutte le intestazioni in forma di array, wp_remote_retrieve_response_code() dà il codice della risposta e wp_remote_retrieve_response_message() restituisce il messaggio della risposta.

Questo è tutto. Quello che dobbiamo sapere è come specificare le intestazioni per fare richieste giuste.

Fare Richieste

Utilizziamo la funzione wp_remote_get() per fare una richiesta. Useremo il primo parametro per impostare l’URL e il secondo per aggiungere argomenti. Potete trovare il set completo dei parametri supportati nel Codex, qui mi concentrerò sulle informazioni dell’header.

Per ottenere il messaggio di stato di un utente da Twitter è necessario utilizzare il percorso statuses/user_timeline.json insieme all’URL https://api.twitter.com/1.1 e passare un bearer token per l’autenticazione – che ho generato in precedenza. Il bearer token deve essere aggiunto come header di autorizzazione nella forma di Bearer [TOKEN].

$token = 'Sijbwrf82wdaBief'; 
$response = wp_remote_get('https://api.twitter.com/1.1/statuses/user_timeline.json?screen_name=kinsta', array(
    'headers' => array(
        'Authorization' => 'Bearer ' . $token
    ),
));

Questa richiesta restituisce una grande quantità di informazioni che possono essere ottenute stampando la variabile $response.Potete anche utilizzare le funzioni di tipo wp_remote_retrieve per ottenere una parte della risposta.

Spesso il corpo contiene le informazioni necessarie, di solito in formato JSON. In PHP possiamo convertirlo facilmente in un array:

$data = json_decode( $response['body'], true )

Accedere all’API di Github

Vediamo un rapido esempio che elencherà i nostri ultimi repo Github in un widget WordPress. Per prima cosa, dovrete accedere a Github e andare al vostro profilo, modificarlo e poi andare su “Personal access tokens”, dove potrete generare un token.

Github Access Tokens
Github Access Tokens

Il passo successivo è creare un template di widget vuoto. Questo widget avrà due opzioni: un posto dove inserire il vostro token API e un titolo. Questo non è il metodo migliore, perché salva il token nel database, ma va bene per il nostro esempio.

class My_Github_Widget extends WP_Widget {

	public function __construct() {
		parent::__construct(
			'my_github_widget',
			'My Github Repos',
			array( 'description' => 'A widget that showcases your Github repos' )
		);
	}

	public function widget( $args, $instance ) {
		// Widget output
	}

	public function form( $instance ) {
		$token = ! empty( $instance['token'] ) ? $instance['token'] : '';
		$title = ! empty( $instance['title'] ) ? $instance['title'] : 'From Github';
		?>
<label for="get_field_id( 'title' ); ?>">Title <input class="widefat" id="get_field_id( 'title' ); ?>" name="get_field_name( 'title' ); ?>" type="text" value="">

<label for="get_field_id( 'token' ); ?>">Github API Token <input class="widefat" id="get_field_id( 'token' ); ?>" name="get_field_name( 'token' ); ?>" type="text" value="">

<?php } }

Non voglio addentrarmi troppo nella creazione dei widget qui. Se volete saperne di più, date un’occhiata alla guida sulla Widget API nel Codex. La cosa importante è che il metodo widget() mostrerà il contenuto del nostro widget. All’interno di quella funzione, ci collegheremo a Github con una richiesta HTTP, poi formatteremo e mostreremo la risposta. Ecco come si fa – tutto il codice che segue va nel metodo widget().

echo $args['before_widget']; 

if ( ! empty( $instance['title'] ) ) { 
  echo $args['before_title'] . apply_filters( 'widget_title', $instance['title'] ). $args['after_title']; 
} 

$args = array( 
  'headers' => array( 
    'Accept' => 'application/vnd.github.v3+json', 
    'Authorization' => 'token 3f4f654ab31c2f15e839c74c952e5de2f562f1ee' 
  ) 
); 

$response = wp_remote_get( 'https://api.github.com/user/repos', $args ); 
$repos = json_decode( $response['body'], true ); 

if( !empty( $repos ) ) { 
  echo '<ul>'; 
  foreach( $repos as $repo ) { 
    echo '<li><a href="' . $repo['url'] . '" target="_blank">' . $repo['name'] . '</a></li>'; 
  } 
  echo '</ul>'; 
} 

echo $args['after_widget'];

Si inizia semplicemente aggiungendo l’elemento wrapper del widget e il titolo in alto e si conclude chiudendo il wrapper del widget, la sezione principale del codice è tra i due.

Per prima cosa ho impostato gli header della richiesta HTTP. La prima domanda potrebbe essere: come faccio a sapere quali parametri aggiungere? L’header Authorization è la parte più importante. L’ho letto nella sezione Authentication della documentazione sull’API.

L’header Accept non è richiesto, ma in cima alla stessa pagina della documentazione la guida vi incoraggia a fornirlo.

Poi uso json_decode() sul corpo della risposta e faccio un ciclo sull’array risultante, creando un elenco di link.

Passaggi Successivi

Se pensate che sia stato facile, avete assolutamente ragione, lo è! La parte difficile è assicurarsi di avere tutto quello che serve senza sprecare risorse. Ci sono due problemi nel codice che richiederebbero la nostra immediata attenzione.

Se c’è qualche problema con l’API – ad esempio errori sconosciuti, account limitati da tariffe e così via – potremmo imbatterci in un grosso errore. Stiamo solo controllando se il body è vuoto prima di mostrare la lista.

Se ci imbattiamo in un errore, è probabile che il body contenga informazioni sull’errore, quindi non sarebbe vuoto neanche in questo caso. È probabile che elencheremmo gli elementi dell’errore di risposta, ma, dato che questi non avrebbero le proprietà url e name, ci ritroveremmo con elementi di lista vuoti e avvisi PHP.

Il secondo problema è che questo è solo uno spreco. Ci stiamo connettendo ad un servizio esterno ad ogni caricamento di pagina, il che potrebbe richiedere un pedaggio ai nostri server e potrebbe causare la limitazione dell’account su Github. Anche se non è il nostro caso, quanto è probabile che la vostra lista di repo Github cambi tra due visualizzazioni di pagina, e quanto è importante avere informazioni aggiornate?

Personalmente cin un caso come questo onsiglierei di utilizzare i transient. Un transient vi permette di memorizzare la risposta della richiesta con un tempo di scadenza. Se impostate la scadenza a un giorno, i dati saranno recuperati da Github una volta, poi direttamente dal vostro database per le successive 24 ore. Dopo la scadenza viene recuperato di nuovo da Github e salvato nel database.

Questo riduce le vostre chiamate API da una per ogni caricamento di pagina a una al giorno, che è un enorme miglioramento e non è nemmeno un grande compromesso.

Riepilogo

Con WordPress è facile interagire con le API di tutto il web. L’utilizzo di un paio di funzioni integrate vi permetterà di estrarre dati più ricchi e rilevanti per i vostri utenti.

Con la sanitizzazione, il controllo degli errori e un meccanismo di caching, si può costruire un’applicazione efficiente che non solo è più utile, ma è fa un consumo meno intenso di risorse di quanto si possa immaginare.

Fateci sapere se avete utilizzato l’API HTTP di WordPress per connettere WordPress con un’API di terze parti, sarebbe bello conoscere il vostro lavoro!

Daniel Pataki

Hi, my name is Daniel, I'm the CTO here at Kinsta. You may know me from Smashing Magazine, WPMU Dev, Tuts+ and other WordPress/Development magazines. Aside from WordPress and PHP I spend most of my time around Node, React, GraphQL and other technologies in the Javascript space.

When not working on making the best hosting solution in the Universe I collect board games, play table football in the office, travel or play guitar and sing in a pretty bad band.