Guida Base alla REST API di WordPress

La REST API sta per cambiare WordPress. Potreste non averlo notato, visto che molto avviene dietro le quinte, ma la REST API avrà un grande impatto sul futuro di WordPress, sia in termini di codebase che di utilizzo.

Se non avete lavorato con la REST API di WordPress, potreste chiedervi di cosa si tratta. Quindi iniziamo subito a vedere cos’è la REST API.

Che Cos’è la REST API di WordPress?

La REST API di WordPress è un’interfaccia che gli sviluppatori possono utilizzare per accedere a WordPress dall’esterno dell’installazione. È possibile accedervi utilizzando JavaScript, il che significa che può essere utilizzata per creare siti web e applicazioni interattive.

REST sta per Representational State Transfer e API sta per Application Programming Interface. Vediamo cosa significano entrambi.

Cos’è una Application Programming Interface (API)?

Un’Application Programming Interface, o API, è definita come segue:

“Un’interfaccia o protocollo di comunicazione tra un client e un server per semplificare la costruzione di software lato client.”

Se non si ha familiarità con le API, questa definizione potrebbe non essere di grande aiuto. Per metterla in modo più semplice, un’API è un insieme di istruzioni che permette ad un sistema di interagire (o “interfacciarsi”) con un altro. Se avete mai aggiunto una mappa di Google al vostro sito WordPress , avete usato l’API di Google Maps, che permette al vostro sito WordPress di interfacciarsi con le maoppe di Google.

Questi sistemi non devono essere completamente separati. WordPress ha già più API per cose come plugin, impostazioni e shortcode. Queste API possono essere utilizzate dagli sviluppatori di plugin e temi per interagire con il core di WordPress e far succedere delle cose (come la creazione di scorciatoie e l’aggiunta di schermate di impostazioni per il pannello di amministrazione di WordPress).

La differenza con la REST API è che questa permette a sistemi esterni all’installazione di WordPress di interagire con WordPress, cosa in cui entra in azione la parte REST.

Che cos’è il Representational State Transfer (REST)?

Il Representational State Transfer, o REST, fornisce standard che i sistemi web possono utilizzare per interfacciarsi tra loro. Senza REST, due sistemi non sarebbero in grado di capirsi e quindi di inviare dati in un senso o nell’altro.

Affinché un’applicazione sia RESTful, deve essere conforme a cinque principi:

1. Interfaccia uniforme. Gli URL utilizzati per accedere alle risorse del sistema devono essere uniformi, coerenti e accessibili attraverso un approccio comune come GET (su cui diremo molti di più tra poco).
2. Client-server. Le applicazioni client e le applicazioni server devono essere separate, in modo che possano essere sviluppate indipendentemente l’una dall’altra. Se cambia la tecnologia lato server (ad esempio WordPress), l’applicazione lato client (ad esempio un’app) deve essere in grado di accedervi con lo stesso semplice metodo.
3. Senza Stato. Il server non cambia stato quando viene fatta una nuova richiesta utilizzando l’API. Non memorizza le richieste fatte.
4. Memorizzabile nella Cache. Tutte le risorse devono essere memorizzabili in cache, per migliorare la velocità e la conformità agli standard web. La cache può essere implementata sul server o lato client.
5. Sistema a livelli. Un sistema RESTful consente di utilizzare più livelli per accedervi, memorizzando i dati in server intermedi, se necessario. Il server non può dire se il client finale è direttamente collegato ad esso.

Tutti questi vincoli riguardano le pagine web e le applicazioni e regolano il modo in cui un’applicazione può interfacciarsi con l’API.

Cosa Significa Questo per WordPress?

Mettere insieme REST e API significa che la REST API è un insieme di istruzioni codificate per consentire ad altri sistemi di interfacciarsi con WordPress e che è programmate in modo tale da garantire che questi sistemi si capiscano a vicenda.

Significa che un sito web di terze parti o un’applicazione mobile, ad esempio, può accedere al vostro database WordPress, recuperarne e aggiungere dati.

Ci sono però una serie di implicazioni e di utilizzi.

Capire la REST API di WordPress

La REST API di WordPress è stata sviluppata in risposta ai cambiamenti nel modo in cui vengono sviluppati i siti web e le applicazioni e alla necessità di aprire WordPress in modo più esteso.

Lo Sfondo alla REST API di WordPress

La REST API di WordPress è stata rilasciata a dicembre 2016 come parte del core della versione 4.7, ma c’era già prima come plugin.

È progettata per supportare una serie di applicazioni basate su WordPress e per trasformare WordPress da sistema di gestione dei contenuti a piattaforma per applicazioni.

È ampiamente utilizzata da WordPress.com, la cui interfaccia basata su JavaScript utilizza la REST API per interfacciarsi con il database di WordPress. Viene utilizzato anche dall’interfaccia di editing di Gutenberg, che è entrata a far parte del core nel 2019.

La REST API amplia la gamma di applicazioni per le quali è possibile utilizzare WordPress. Mentre un sistema di gestione dei contenuti è eccellente per il funzionamento di un sito web complesso, una application platform può essere utilizzata anche come base per applicazioni web-based a pagina singola o per SPA (se avete mai utilizzato Google docs, allora ne avete conosciuto uno).

In queste applicazioni, il contenuto viene aggiornato quando l’utente esegue un’azione, invece di caricare nuove pagine. Dato che utilizza JavaScript (un linguaggio lato client) invece di PHP (un linguaggio lato server), può far succedere le cose nel browser dell’utente senza dover inviare costantemente richieste al server.

Implicazioni per gli Utenti e gli Sviluppatori di WordPress

Se siete utenti e/o sviluppatori che lavorano con WordPress, la REST API comporta diverse cose.

Per gli utenti ricordiamo:

• Modifiche all’interfaccia, compreso l’editor di Gutenberg.
• Modifiche e miglioramenti all’app mobile di WordPress.
• Pagine di amministrazione di WordPress self-hosted che nel tempo assomigliano di più alle schermate di WordPress.com.

Per gli sviluppatori ci sono implicazioni e possibilità più ampie:

• La possibilità di creare SPAs utilizzando la REST API, attingendo dati da WordPress ma con un aspetto molto diverso da WordPress.
• La capacità di integrare WordPress con altre tecnologie e con altri sistemi frontend.
• La possibilità di sviluppare con WordPress anche se siete sviluppatori frontend ma non PHP.
• Per gli sviluppatori PHP, una crescente necessità di espandere le proprie competenze con JavaScript.
• Cambiamenti specifici come la necessità di costruire blocchi per Gutenberg invece dei meta box nelle schermate di modifica di post e pagine.

Nel tempo, la REST API di WordPress farà sì che una parte maggiore del core di WordPress sarà scritto in JavaScript invece che in PHP. Se siete sviluppatori WordPress, questo significa che dovrete apprendere JavaScript.

Come accedere all’API WordPress REST API

Come si accede alla REST API di WordPress?

Per accedere all’API WP-REST, è necessario accedere al sito tramite la linea di comando. In WordPress questa si chiama WP-CLI . Non è possibile fare nulla di tutto questo attraverso il pannello di amministrazione o accedendo direttamente al codice del vostro sito.

Vediamo come iniziare.

Accedere a WP-REST via WP-CLI

WP-CLI è l’interfaccia a riga di comando di WordPress. Consente di accedere e lavorare con WordPress tramite l’interfaccia a riga di comando (CLI) del computer. WP-CLI è preinstallato con tutti i piani di hosting di Kinsta.

Per accedere alla CLI, aprite il Terminale su Mac o in Linux, o il Prompt dei comandi in Windows.

Per accedere a un sito remoto tramite WP-CLI, è necessario accedere al server via SSH (Non potete connettervi via SSH? Correggette l’errore SSH “Connection Refused”).

Per accedere a un sito locale, è sufficiente utilizzare la corretta struttura delle directory dalla riga di comando. È una buona idea sperimentare con le API REST su un sito di test locale prima di provarlo su un sito live.

Dovrete accedere specificamente alla REST API del vostro sito in questo modo:

http://yoursite.com/wp-json/wp/v2

Potrete quindi aggiungere elementi per accedere ad alcuni tipi di dati, che esamineremo più nel dettaglio a breve. Questi elementi sono chiamati endpoint.

Autenticazione

Una volta effettuato l’accesso al sito, potrebbe essere necessario effettuare l’autenticazione. Alcuni endpoint sono pubblici e non richiedono autenticazione, altri la richiedono.

Qui non state effettuando l’accesso al pannello di amministrazione del vostro sito: la REST API fa le cose un po’ diversamente.

Per autenticare il sito tramite WP-CLI, è necessario installare un plugin di autenticazione. Per le installazioni di sviluppo, il plugin Basic Auth fa il suo lavoro ed è semplice da usare.

Tuttavia, per i siti live, si dovrebbe usare una sistema più solido di autenticazione, come il plugin JWT Authentication , che utilizza JSON Web Token ed è più sicuro.

Potrete quindi utilizzare la riga di comando per accedere ai dati con autenticazione.

L’esempio che segue utilizza curl per testare la connessione a WordPress. Si otterrà un elenco di bozze di articoli.

curl -X GET --user username:password -i http://yoursite.com/wp-json/wp/v2/posts?status=draft

Le bozze degli articoli non sono informazioni pubbliche, quindi per accedervi è necessaria l’autenticazione. Ma se state cercando dati pubblici, non avete bisogno di autenticazione. Quindi, per recuperare un elenco dei messaggi che sono stati pubblicati, è possibile utilizzare:

curl -X GET http://yoursite.com/wp-json/wp/v2/posts

Questo andrebbe a prendere tutti i post pubblicati, proprio perché sono pubblici.

Panoramica dei Comandi della REST API di WordPress

Una volta che siete entrati nel vostro sito e sapete come utilizzare l’autenticazione (e se è necessaria), dovrete utilizzare uno dei tanti comandi per interagire con il sito.

I comandi da utilizzare sono:

• GET recupera una risorsa come un post o altri dati.
• POST aggiunge una risorsa al server, come un post, un allegato o un’altra risorsa.
• PUT può essere utilizzato per modificare o aggiornare una risorsa già presente sul server.
• DELETE rimuove una risorsa dal server. Usatelo con prudenza!

Diamo un’occhiata ad ognuno di questi comandi.

GET

Il comando GET è probabilmente il più utilizzato: questo comando recupera i dati. L’esempio (che si utilizza una volta che si accede con successo al proprio sito) che segue riporta un elenco di tutte le pagine pubblicate nel vostro sito:

GET http://yoursite.com/wp-json/wp/v2/posts/?status=published

Notate che non ho incluso il percorso completo del sito nella riga qui sopra, in quanto avete già avuto accesso tramite WP-CLI.

Una volta recuperati questi dati, potrete utilizzarli come informazioni per il vostro passo successivo. Potreste cancellare uno di questi messaggi, modificarlo o aggiornarlo. Oppure potete semplicemente inviare i post alla vostra applicazione web.

Diciamo che volete recuperare l’ultimo post. Dovreste utilizzare questo comendo:

GET http://yoursite.com/wp-json/wp/v2/posts/?per_page=1

Ci sono una serie di argomenti che potete utilizzare quando lavorate con i post. Si veda il manuale della REST API di WordPress per maggiori informazioni.

POST

Utilizzate POST per aggiungere dati o risorse al vostro sito.

Quindi, ad esempio, se volete creare un post, potete iniziare con un comando POST:

POST http://yoursite.com/wp-json/wp/v2/posts/

In questo modo si crea una bozza vuota di articolo.

Potrete quindi aggiornare il post utilizzando un comando PUT per modificarlo.

Con un comando POST potete anche aggiungere altre risorse, oltre agli articoli, come allegati e altri tipi di post.

Per aggiungere una pagina al vostro sito, potreste utilizzare qualcosa del genere:

POST http://yoursite.com/wp-json/wp/v2/posts/pages

Questo creerebbe una pagina vuota allo stesso modo in cui si crea un post vuoto.

PUT

Il comando PUT consente di modificare una risorsa esistente, compresi i post.

Diciamo che avete un certo numero di bozze di articoli nel vostro sito. Volete controllarli e aggiornarne uno per pubblicarlo.

Potreste iniziare cercando una lista di tutte le bozze di post:

POST http://yoursite.com/wp-json/wp/v2/posts/?status="draft"

Il sistema vi fornirà un elenco di tutte le bozze degli articoli correnti. È possibile modificare lo stato di uno di questi utilizzando il suo ID:

PUT /wp/v2/posts/567

Questo accede a quel post e vi permette di modificarlo. Potrete quindi modificarne lo stato utilizzando l’argomento status:

{
"status" = "publish"
}

Oppure potete aggiungere contenuti al post e pubblicarlo:

{
"status" = "publish"
"content" = "content here"
}

Il server restituirà uno stato 200 - OK che vi dice che la richiesta PUT ha modificato con successo il messaggio.

DELETE

Il comando DELETE fa quello che ci si aspetterebbe: cancella una risorsa. Di default, se lo utilizzate per eliminare un post, il comando lo sposterà nel cestino invece di cancellarlo definitivamente.

Quindi, se voleste spostare il post appena creato nel cestino, dovreste utilizzare questo comando:

DELETE http://yoursite.com/wp-json/wp/v2/posts/567

Tuttavia, se si volesse bypassare il cestino e cancellarlo definitivamente, si dovrebbe utilizzare l’argomento force:

DELETE http://yoursite.com/wp-json/wp/v2/posts/567?force=true

Questo cancella permanentemente il messaggio senza possibilità di annullamento, quindi deve essere utilizzato con cautela.

Quando non Utilizzare la REST API di WordPress

La REST API di WordPress non è sempre lo strumento giusto per sviluppare un sito web o un’applicazione. Ecco alcune considerazioni di cui dovreste essere consapevoli prima di utilizzarla per lo sviluppo:

Compatibilità

Se la vostra applicazione sarà utilizzata su dispositivi che non eseguono JavaScript o da utenti che possono averla disattivata, allora non funzionerà con la REST API.

Un sito WordPress in PHP genera codice HTML, quindi non soffre di questo problema. I dispositivi che non utilizzano JavaScript sono sempre più rari, ma se si sviluppa specificamente per questi dispositivi, la REST API non funzionerà.

Allo stesso modo, se è possibile che gli utenti disattivino JavaScript, allora lavorare con le API REST causerà dei problemi. Alcuni utenti disattivano JavaScript nel loro browser per motivi di accessibilità o di sicurezza.

Accessibilità

Siti e applicazioni sviluppate con JavaScript non sono sempre accessibili come quelli in HTML.

Questo è dovuto in gran parte al modo in cui JavaScript viene utilizzato per fornire contenuti dinamici che potrebbero non andar bene con gli screen reader e potrebbero causare problemi alle persone con disabilità visive o epilessia fotosensibile.

Utilizzare la REST API per accedere al vostro sito WordPress e produrre dati in una forma progettata per essere accessibile significa che potete superare questi problemi, ma vale la pena verificare l’accessibilità del vostro sito mentre siete in sviluppo.

SEO

Le applicazioni a pagina singola, che si aggiornano frequentemente, possono talvolta causare problemi di SEO . Questo perché il contenuto che non viene consegnato quando la pagina viene visualizzata per la prima volta potrebbe non essere indicizzato dai motori di ricerca.

Google e altri motori di ricerca stanno recuperando il ritardo con il fatto che molti siti web sono ora alimentati da SPA e li stanno indicizzando in modo appropriato. Ma vale la pena di fare una verifica SEO approfondita di qualsiasi sito sviluppato utilizzando la REST API.

Come Disattivare la REST API di WordPress

Se non volete che le applicazioni siano in grado di accedere ai dati del vostro sito utilizzando la REST API, potete disattivarla. Ricordate che i dati pubblici potrebbero essere accessibili a chiunque, non solo a voi.

Per farlo, è possibile installare il plugin Disable WP REST API . Questo plugin disabilita la REST API per chiunque non sia connesso al vostro sito.

In alternativa, potete aggiungere del codice al file functions del tema o scrivere un vostro plugin. È meglio scrivere un plugin in quanto non si tratta di funzionalità specifiche del tema.

Nel plugin aggiungete solo due righe:

add_filter( 'json_enabled', '__return_false' );
add_filter( 'json_jsonp_enabled', '__return_false' );

Questo disabiliterà completamente la REST API per il vostro sito. Potrebbe avere effetti a catena per le schermate di amministrazione, quindi accertatevi che tutto funzioni correttamente dopo aver attivato il plugin.

Applicazioni del Mondo Reale che Utilizzano la REST API di WordPress

La REST API presenta alcune interessanti possibilità per il futuro di WordPress. Ecco alcuni esempi di applicazioni e siti che utilizzano la REST API di WordPress per creare SPA o per collegare WordPress ad altri siti e tecnologie.

WordPress.com

Le schermate di amministrazione di WordPress.com sono costruite interamente utilizzando la REST API per fornire una SPA con cui gli utenti interagiscono per gestire il proprio sito.

Questo rende dinamica la comunicazione tra l’interfaccia e il server e si traduce in un’interfaccia user-friendly che WordPress.org adotta nel tempo.

L’Editor a Blocchi (Gutenberg)

Anche questo si trova nelle schermate di amministrazione di WordPress, ma questa volta anche nelle installazioni indipendenti di WordPress, l’editor a blocchi di Gutenberg utilizza la REST API per comunicare con il vostro database e creare blocchi.

Affinché i tipi di post funzionino con l’editor Gutenberg, la REST API deve essere abilitata. Il che significa che, se state registrando un custom post type e state utilizzando Gutenberg, dovrete aggiungere la seguente riga per abilitare l’editor a blocchi per quel tipo di post:

"show_in_rest" = true;

Event Espresso

Event Espresso è un plugin WordPress che permette agli utenti di organizzare e pubblicizzare eventi. Utilizza la REST API in modo che gli utenti possano accedere ai dati dall’esterno di WordPress. Questo significa che potete costruire app mobili o SPA per gestire i vostri eventi.

UsTwo

UsTwo è un’agenzia digitale il cui sito è stato realizzato utilizzando la REST API come applicazione a pagina singola. Questo combina un front-end costruito utilizzando React con un backend alimentato da WordPress (lettura suggerita: Una Guida Per Avviare e Gestire un’Agenzia WordPress di Successo).

Il contenuto della pagina singola è modulare, con una struttura diversa da quella di una pagina WordPress standard. Per fare questo lavoro, utilizzano un plugin personalizzato per la creazione di pagine che permette al loro team di aggiungere contenuti modulari al sito.

USA Today

Il sito web di USA Today è stato ricostruito integrando la REST API di WordPress con i sistemi e i moduli esistenti nel sito.

La REST API ha permesso che il contenuto del sito fosse esteso ad altri punti vendita come Facebook Instant Articles e Apple News, utilizzando JSON. Hanno anche sviluppato un social game online per la loro sezione sportiva, costruito utilizzando JavaScript.

Riepilogo

La REST API di WordPress pone alcune interessanti sfide ma anche grandi opportunità sia per gli utenti di WordPress che per gli sviluppatori. È il futuro di WordPress e probabilmente cambierà radicalmente il modo in cui sviluppiamo con WordPress e il modo in cui lo utilizziamo.

Cosa ne pensate della REST API? L’avete utilizzata per alcuni dei vostri progetti? Raccontateci la vostra esperienza nei commenti qui sotto!