L’HTTP API di WordPress consiste in una serie di funzioni che permettono di fare chiamate HTTP molto più facilmente. Non c’è più bisogno di armeggiare con file_get_contents o cURL, perché l’API offre una singola interfaccia unificata. Questo è ottimo per interagire con le API di terze parti, specialmente quelle REST-ful come Twitter, Facebook, MailChimp e altre.
Le Basi di HTTP
Abbiamo già visto tutti HTTP in azione. Infatti, se questa fosse per voi la prima volta in assoluto sul web e questa la prima cosa che state leggendo, avete già visto l’HTTP fare la sua magia. L’HTTP è un protocollo di rete utilizzato per fornire tutti i file e i dati (risorse) attraverso l’Interweb.
Ci sono fondamentalmente due parti dell’equazione: la richiesta HTTP e la risposta HTTP, o transazione. Sia la richiesta che la risposta sono molto simili nella struttura, entrambe sono composte da quattro parti:
- Una linea iniziale
- Zero o più linee di intestazione
- Una linea vuota
- Un body di contenuto opzionale
La Linea Iniziale
Le richieste utilizzano la riga iniziale per inviare tre informazioni: il nome del metodo, il percorso e la versione HTTP. Per esempio, visualizzando la pagina principale del blog di Kinsta, dovreste vedere questo nella riga iniziale della richiesta.
GET /blog/ HTTP/1.1Le risposte forniscono anche tre informazioni, anche se in qualche modo diverse: La versione HTTP, il codice di risposta e una descrizione della risposta. Quando si fa una richiesta al blog principale di Kinsta, questo invia una risposta HTTP con la seguente riga iniziale:
HTTP/1.0 200 OKHeader
Gli header contengono varie informazioni sulla richiesta o sulla risposta. HTTP 1.1 definisce 46 tipi di intestazioni, ma solo una è richiesta (solo per le richieste), l’intestazione “Host”. Date un’occhiata allo screenshot dei miei developer tools di Chrome che mostra alcune delle intestazioni inviate al blog principale di Kinsta insieme ad una richiesta:
Body
Il body di solito contiene dati sulla risorsa richiesta. Se si invia una richiesta GET al blog principale di Kinsta si dovrebbe ricevere l’HTML richiesto per rendere la pagina (la risorsa) nel contenuto del body.
Altre Informazioni
Questo è tutto quello che dovete sapere per ora sull’HTTP. Ci concentreremo soprattutto sul nome del metodo (GET,POST,etc), sulle intestazioni e sul body. Se volete saperne di più, consiglio la spiegazione di James Marshall sull’HTTP, è un primer molto ben scritto per chi vuole conoscere meglio il protocollo.
Informazioni sulle API Restful
Le API Restful API, o metodologia REST, hanno lo scopo di fornire un modo semplice e standard per interagire con un’applicazione (qui potete saperne di più sulle basi della REST API di WordPress). Spesso sono usate in combinazione con HTTP per creare un sistema di interazioni molto comprensibile. Si basano su percorsi e verbi HTTP.
I verbi HTTP sono gli stessi nomi dei metodi che abbiamo visto prima, i più comuni sono: GET, POST, PUT, PUT, DELETE. Penso che PUT sia l’unico ambiguo qui, pensatelo come un comando di aggiornamento. Quando usiamo questi verbi insieme ai percorsi possiamo costruire un sistema significativo:
GET /post/1/ utilizzato per recuperare il post con l’ID di 1. DELETE DELETE /post/1/ utilizzato per cancellare lo stesso post. Potremmo anche usare PUT /post/1/ per aggiornarlo, fornendo informazioni rilevanti nel corpo della richiesta e nelle intestazioni.
Dovreste vedere che solo aggiungendo una versione HTTP ai codici qui sopra abbiamo in realtà la linea iniziale di una transazione HTTP, che è solo uno dei motivi per cui questo sistema è così potente.
Usare l’API HTTP di WordPress
Armati di tutte queste conoscenze, possiamo facilmente comprendere come funziona l’API HTTP di WordPress. I quattro metodi utilizzati per fare richieste e intercettare le risposte sono:
wp_remote_get()wp_remote_post()wp_remote_head()wp_remote_request()
Le prime due funzioni sono autoesplicative, utilizzano nella richiesta rispettivamente il metodo GET e il metodo POST. La terza funzione utilizza il metodo HEAD, di cui non abbiamo ancora parlato. Questo metodo è usato per recuperare solo le intestazioni di una risposta. Questo può far risparmiare molto sulle spese generali se abbiamo solo bisogno di alcuni metadati su una risorsa. La funzione finale è una funzione generica, si può specificare quale metodo si vuole usare all’interno dei parametri della funzione.
Ci sono cinque funzioni aggiuntive che possiamo utilizzare per recuperare parti specifiche della risposta. Queste sono fondamentalmente delle scorciatoie per navigare nella massa di dati che riceviamo:
wp_remote_retrieve_body()wp_remote_retrieve_header()wp_remote_retrieve_headers()wp_remote_retrieve_response_code()wp_remote_retrieve_response_message()
La Nostra Prima Richiesta HTTP
Facciamo un rapido test recuperando le informazioni dell’header del blog di Kinsta. Lo si può fare ovunque all’interno di un plugin o di un tema, ma ovviamente si dovrebbe essere all’interno di un ambiente di test per assicurarsi di non produrre testo indesiderato su un sito live.
$response = wp_remote_head( 'https://kinsta.com/blog/' );
var_dump( $response )Come si può vedere dalla risposta che otteniamo qui sotto, la sezione del body è vuota (dato che stiamo usando il metodo HEAD) e sono mostrate tutte le intestazioni. Per prendere solo gli header senza tutti gli altri elementi dell’array, potremmo usare la funzione wp_remote_retrieve_headers().
array (size=5)
'headers' =>
array (size=13)
'server' => string 'nginx' (length=5)
'date' => string 'Wed, 22 Jul 2015 14:22:07 GMT' (length=29)
'content-type' => string 'text/html; charset=UTF-8' (length=24)
'connection' => string 'close' (length=5)
'vary' => string 'Accept-Encoding' (length=15)
'x-pingback' => string 'https://kinsta.com/xmlrpc.php' (length=29)
'x-powered-by' => string 'HHVM/3.8.0' (length=10)
'link' => string '; rel="https://github.com/WP-API/WP-API"' (length=68)
'x-frame-options' => string 'DENY' (length=4)
'x-content-type-options' => string 'nosniff' (length=7)
'strict-transport-security' => string 'max-age=31536000' (length=16)
'x-kinsta-cache' => string 'HIT' (length=3)
'content-encoding' => string 'gzip' (length=4)
'body' => string '' (length=0)
'response' =>
array (size=2)
'code' => int 200
'message' => string 'OK' (length=2)
'cookies' =>
array (size=0)
empty
'filename' => nullDare un Senso alle API
La più grande barriera che vedo per gli sviluppatori è la quantità di nuove cose che devono mettere in atto per far funzionare una chiamata API. Bisogna conoscere l’HTTP, come fare richieste e anche come autenticarsi correttamente. Senza di questo, ogni singola chiamata fallirà. Vediamo un esempio attraverso le API di Twitter, dato che hanno un’ottima documentazione.
Ci occuperemo dell’Application-only Authentication (che è un flusso più semplice). Seguirò gli stessi passaggi suggeriti da Twitter. Prima di iniziare, assicuratevi di creare un’applicazione Twitter.
Dovreste essere in grado di aggiungere il codice qui sotto in qualsiasi punto di un tema o di un plugin, ma, come prima, assicuratevi di utilizzare un sito di prova!
Passo 1: Encode di Consumer Key e Secret
Una volta creata un’applicazione, si dovrebbe avere a portata di mano una chiave utente e un segreto. Per rendere le cose più semplici, creiamo delle costanti che contengano queste informazioni.
define( 'TWITTER_CONSUMER_KEY', '12disnir382jeqwdasd23wdasi' );
define( 'TWITTER_CONSUMER_SECRET', '23wdajskduhtrq2c32cuq9r8uhuf' )I tre passaggi per la creazione di una versione codificata di questi valori sono illustrati nella documentazione:
- URL encode di consumer key e consumer secret
- Concatenazione con due punti (:)
- Codifica Base64 dell’intera stringa
In PHP tutto questo sarà abbastanza facile da fare. Ecco qua!
$key = urlencode( TWITTER_CONSUMER_KEY );
$secret = urlencode( TWITTER_CONSUMER_SECRET );
$concatenated = $key . ':' . $secret;
$encoded = base64_encode( $concatenated );
Passo 2: Ottenere un Token al Portatore
Invece di utilizzare la vostra vera password, inviate a Twitter la vostra stringa codificata (che utilizza le vostre credenziali API) per ricevere un pass temporaneo valido per un determinato periodo di tempo. Per farlo, faremo una richiesta HTTP, ecco cosa ha da dire Twitter:
- La richiesta deve essere una richiesta HTTP POST.
- La richiesta deve includere un’intestazione di autorizzazione con il valore di Basic.
- La richiesta deve includere un’intestazione Content-Type con il valore di application/x-wwww-form-urlencoded;charset=UTF-8.
- Il corpo della richiesta deve essere grant_type=client_credentials.
Cominciamo dalle basi. Sappiamo che abbiamo bisogno di una richiesta POST, quindi useremo wp_remote_post(). La funzione prende due parametri; il primo è l’URL, il secondo contiene argomenti opzionali. L’URL sarà https://api.twitter.com/oauth2/token, useremo il secondo parametro per gestire tutti gli altri requisiti.
$args = array(
'headers' => array(
'Authorization' => 'Basic ' . $encoded,
'Content-Type' => 'application/x-www-form-urlencoded;charset=UTF-8'
),
'body' => 'grant_type=client_credentials'
);
$response = wp_remote_post( 'https://api.twitter.com/oauth2/token', $args );
Le intestazioni devono essere aggiunte come array, il tipo di intestazione è la chiave, il valore sarà il valore dell’elemento dell’array. Il corpo deve essere una stringa. In caso di successo, si dovrebbe vedere una risposta simile a quella sottostante.
array (size=5)
'headers' =>
array (size=23)
'cache-control' => string 'no-cache, no-store, must-revalidate, pre-check=0, post-check=0' (length=62)
'content-disposition' => string 'attachment; filename=json.json' (length=30)
'content-encoding' => string 'deflate' (length=7)
'content-length' => string '142' (length=3)
'content-type' => string 'application/json;charset=utf-8' (length=30)
'date' => string 'Wed, 22 Jul 2015 14:47:37 GMT' (length=29)
'expires' => string 'Tue, 31 Mar 1981 05:00:00 GMT' (length=29)
'last-modified' => string 'Wed, 22 Jul 2015 14:47:37 GMT' (length=29)
'ml' => string 'A' (length=1)
'pragma' => string 'no-cache' (length=8)
'server' => string 'tsa_b' (length=5)
'set-cookie' => string 'guest_id=v1%3A14375720938219946; Domain=.twitter.com; Path=/; Expires=Fri, 21-Jul-2017 14:47:37 UTC' (length=100)
'status' => string '200 OK' (length=6)
'strict-transport-security' => string 'max-age=631138519' (length=17)
'x-connection-hash' => string 'd8b10926f99dwef93rd7edbe5a71a97a' (length=32)
'x-content-type-options' => string 'nosniff' (length=7)
'x-frame-options' => string 'SAMEORIGIN' (length=10)
'x-response-time' => string '34' (length=2)
'x-transaction' => string 'ef0ebwefweece62ef' (length=16)
'x-tsa-request-body-time' => string '0' (length=1)
'x-twitter-response-tags' => string 'BouncerCompliant' (length=16)
'x-ua-compatible' => string 'IE=edge,chrome=1' (length=16)
'x-xss-protection' => string '1; mode=block' (length=13)
'body' => string '{"token_type":"bearer","access_token":"AAAAAAAAAAAAAAAAAAAAAFoafQAAAAAAqg%2BxmuH83hjsod6crH5bKTUX9Arc%3D5dWpp0XCTDjyiXxMC7LDLg8JbzPdGlCsJi2R1qjY1FMksTAFyG"}' (length=155)
'response' =>
array (size=2)
'code' => int 200
'message' => string 'OK' (length=2)
'cookies' =>
array (size=1)
0 =>
object(WP_Http_Cookie)[303]
public 'name' => string 'guest_id' (length=8)
public 'value' => string 'v1:143757645770219946' (length=21)
public 'expires' => int 1500648457
public 'path' => string '/' (length=1)
public 'domain' => string '.twitter.com' (length=12)
'filename' => nullIl punto culminante di tutto ciò è il token di accesso che si trova nel corpo della risposta. Recuperiamolo ora usando le nostre pratiche funzioni di WordPress. Proseguendo con il nostro precedente esempio, potremmo prendere il token di accesso utilizzando il seguente codice:
$body = wp_remote_retrieve_body( $response );
$body = json_decode( $body, true );
$access_token = $body['access_token'];Passo 3: Utilizzare il Bearer Token
L’ultimo passo è semplicemente quello di utilizzare questo token al portatore in tutte le altre chiamate API. Dobbiamo aggiungerlo come header “Authorization” con il valore: Bearer [bearer_token]. Facciamo una semplice chiamata API che recupera gli ultimi tweet di un utente usando il percorso user_timeline.
$url = 'https://api.twitter.com/1.1/statuses/user_timeline.json?screen_name=danielpataki&count=3';
$args = array(
'headers' => array(
'Authorization' => 'Bearer ' . $access_token,
),
);
$response = wp_remote_get( $url, $args );
$tweets = json_decode( wp_remote_retrieve_body($response), true )
Alla fine di tutto questo, la variabile $tweets conterrà una serie di tweet. È possibile utilizzare varie proprietà di questo array per visualizzare il tweet o manipolare i dati.
Conclusioni
Come potete vedere, utilizzare l’API HTTP di WordPress per la connessione a servizi esterni non è così difficile. Molte delle API di oggi sono costruite intorno agli stessi principi REST – una volta che ne imparate una, ne imparerete altre molto velocemente.
Tenete presente che ogni volta che la documentazione vi chiede di usare il body, usate il body, e quando richiede delle intestazioni, aggiungete tutte quelle necessarie. Poi guardate la risposta, convertitela in un array, prendete i dati che vi servono e usateli. Tutto qui.
Se qualcuno ha già lavorato con un’API particolarmente buona o cattiva, o se avete qualche consiglio e qualche trucco con l’API HTTP di WordPress, fatecelo sapere nei commenti!
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.
Lascia un commento