La REST API di WordPress fornisce un'interfaccia che permette ad applicazioni esterne di interagire con un sito WordPress inviando e ricevendo dati come oggetti JSON, errori inclusi. Grazie alla REST API è possibile sfruttare la flessibilità e la facilità di gestione del back-end di WordPress impiegando tecnologie alternative per il rendering della parte front-end del sito.
WordPress e REST API
La REST API è alla base dell'editor di blocchi e può essere utilizzata per consentire a qualsiasi applicazione web, interna o esterna a WordPress, di accedere ai dati dell'installazione in totale sicurezza e al contempo garantendo elevate performance. L'accesso ai dati avviene nel rispetto delle stesse restrizioni di WordPress: i contenuti pubblici sono accessibili anonimamente, mentre i contenuti privati, protetti da password, gli utenti interni, i metadati, ecc. sono disponibili solo previa autenticazione.
Una volta autenticati, tramite la REST API è possibile eseguire qualsiasi operazione di amministrazione, e questo permette di creare applicazioni che integrino gli strumenti di gestione predefiniti di WordPress, ma anche di creare interfacce alternative per l'amministrazione del sito. Il vantaggio principale della REST API di WordPress è che questa consente di accedere ai dati in modo rapido e senza compromettere la sicurezza o la privacy del sito.
L'API fornisce endpoint REST che rappresentano gli articoli, le pagine, le tassonomie e altri tipi di dati. Un'applicazione può inviare e ricevere dati JSON da questi endpoint per interrogare, modificare e creare contenuti sul sito (operazioni CRUD - Create, Read, Update, Delete). Naturalmente, non è necessario utilizzare la REST API di WordPress in ogni situazione, perché il framework dispone di funzioni, metodi, filtri e azioni che permettono di eseguire ogni tipo di operazione sui dati del sito.
La REST API è uno strumento estremamente utile per sviluppare interfacce personalizzate, garantire sicurezza e prestazioni, creare applicazioni in linguaggi diversi da PHP e agnostiche rispetto all'origine dei dati.
API e oggetti JSON
Ad ogni richiesta, l'API risponde con un oggetto JSON. Queste le risorse disponibili:
| Risorsa | Route |
|---|---|
| Post | /wp/v2/posts |
| Revisioni dei Post | /wp/v2/posts/<id>/revisions |
| Categorie | /wp/v2/categories |
| Tag | /wp/v2/tags |
| Pagine | /wp/v2/pages |
| Revisioni delle Pagine | /wp/v2/pages/<id>/revisions |
| Commenti | /wp/v2/comments |
| Tassonomie | /wp/v2/taxonomies |
| Media | /wp/v2/media |
| Utenti | /wp/v2/users |
| Tipi di Post | /wp/v2/types |
| Stato dei Post | /wp/v2/statuses |
| Impostazioni | /wp/v2/settings |
| Temi | /wp/v2/themes |
| Ricerca | /wp/v2/search |
| Tipi di Blocco | /wp/v2/block-types |
| Blocchi | /wp/v2/blocks |
| Revisioni dei Blocchi | /wp/v2/blocks/<id>/autosaves/ |
| Rendered dei Blocchi | /wp/v2/block-renderer |
| Elementi della Block Directory | /wp/v2/block-directory/search |
| Plugin | /wp/v2/plugins |
La route
La route è un URI che può essere mappato su diversi metodi HTTP. La mappatura ad una route di un singolo metodo HTTP costituisce un endpoint.
Se in WordPress sono stati abilitati i pretty permalink, una richiesta GET all'URI http://example.com/wp-json/ genera una risposta che espone tutte le route disponibili e gli endpoint di ciascuna route. La route /wp-json/ ha solo un endpoint GET, come mostrato nell'immagine che segue.
La route /wp-json/ di una risposta JSON a una richiesta GET
La route wp-json/wp/v2/posts ha invece due endpoint:
GETrestituisce un elenco di post;POSTaccetta richieste autenticate per creare nuovi post.
Oltre a route ed endpoint predefiniti, gli sviluppatori possono aggiungerne di propri. Se i pretty permalink non sono stati abilitati, bisognerà utilizzare una querystring come http://example.com/?rest_route=/ che genera la stessa risposta JSON dell'esempio precedente. In questo caso, una richiesta a http://example.com/wp-json/ genererà un errore 404.
I dati della richiesta alla REST API vengono memorizzati in un'istanza della classe WP_REST_Request, mentre la risposta dell'API è memorizzata in un'istanza della classe WP_REST_Response.
Testare le richieste alla REST API
Per provare le richieste alla REST API di WordPress e analizzare i campi della risposta, basterà digitare la URI della richiesta in un client come Postman.
Esempio di una richiesta GET nell'applicazione web Postman
Per ottenere l'elenco dei dati forniti dall'API, si può trasmettere una richiesta OPTIONS.
OPTIONS https://example.com/wp-json/wp/v2/postsL'immagine che segue mostra la risposta ad una richiesta OPTIONS nel client web di Postman:
Una richiesta OPTIONS alla REST API di WordPress
Un altro strumento utile è il JSON viewer di Firefox.
Schema di una risposta JSON in Firefox
Se si preferisce Chrome, consigliamo l'estensione JSON formatter.
Dopo questa breve introduzione, nella prossima lezione analizzeremo più dettagliatamente richieste e risposte della Rest API di WordPress.
