Una feature che è entrata solo recentemente a far parte del core di WordPress è la REST API. Si tratta di un set di istruzioni che utilizza tutte le funzionalità native di HTTP, tra cui l'autenticazione e i metodi, e rende possibile accedere, sia in lettura che in scrittura, ai dati del database di WordPress. Grazie alla REST API chi sviluppa Web App può occuparsi esclusivamente delle UI, senza preoccuparsi dell'architettura dei dati.
Per attivare il servizio è (al momento) necessario istallare WordPress REST API V2, il plugin rende accessibili le seguenti risorse in formato JSON:
-
- Posts
- Post Revisions
- Categories
- Tags
- Pages
- Comments
- Taxonomies
- Media
- Users
- Post Types
- Post Statuses
- Settings
L'accesso all'API avviene in sola lettura tramite richieste non autenticate, oppure attraverso accessi autenticati per creare, modificare o eliminare risorse.
Concetti generali
Il tipo di accesso viene determinato dal metodo della richiesta HTTP:
- HEAD
- GET
- POST
- PUT
- DELETE
- OPTIONS
Dai metodi, o verbi, dipendono le funzioni che operano sui dati. Queste funzioni vengono definite endpoint. Una volta istallato il plugin WordPress REST API sarà possibile trasmettere richieste HTTP con URL strutturate come segue:
http://nomesito.com/wp-json/wp/v2/posts/456Questa richiesta costituisce un endpoint e potrà essere trasmessa con i metodi GET, POST e DELETE a seconda che si voglia accedere ai dati in lettura, modifica o eliminazione. L'endpoint si compone delle seguenti parti:
| Componente | Descrizione |
|---|---|
/wp-json |
Base dell'endpoint. |
/wp |
Namespace del plugin. |
/v2 |
Versione dell'API. |
/posts/ |
456 è la risorsa cui si chiede accesso (in questo caso il post con ID 456). |
/wp/v2/posts/456 |
Route dell'API. |
Per analizzare la risposta dell'API basterà digitare l'URL precedente, ovviamente indirizzata ad un sito esistente, nella barra degli indirizzi del browser o trasmetterla tramite un client HTTP come Postman.
Restituzione dei dati
Per ottenere l'elenco dei dati forniti dall'API si possono inviare richieste OPTIONS e GET, una OPTIONS restituisce lo schema dei dati della REST API, indispensabile per formulare richieste con GET e POST. Sempre tramite un client HTTP si invii la seguente richiesta:
OPTIONS http://nomesito.com/wp-json/wp/v2/postsLa risposta sarà un oggetto JSON le cui proprietà forniranno l'elenco degli endpoint, dei metodi e degli argomenti.
Gli argomenti vengono corredati dalla proprietà description, utile per la costruzione delle richieste. La seguente richiesta GET fornisce l'elenco delle risorse:
GET http://nomesito.com/wp-json/wp/v2La risposta dell'API sarà l'elenco delle route:
Ognuna delle route dispone delle proprietà:
namespacemethodsendpoints_link
Ogni endpoint dispone a sua volta delle proprietà methods e args. Per fare un esempio, dopo aver inviato tramite client HTTP la precedente richiesta GET, si analizzi la route /wp/v2/posts visualizzata nell'immagine seguente:
La risposta dell'API fornisce tutti i dati necessari a formulare una richiesta HTTP. L'esempio conclusivo dimostrerà come costruire la richiesta.
Accesso alla REST API
Una volta noti i metodi, gli endpoint e gli argomenti, lo sviluppatore è in grado di trasmettere ogni tipo di richiesta. Si supponga di richiedere all'API l'elenco di tutti i post appartenenti alla categoria con ID pari a 2. La richiesta che si dovrà trasmettere sarà:
GET http://nomesito.com/wp-json/wp/v2/posts?categories=2/wp/v2/posts è la route che individua la risorsa, categories è l'argomento che viene passato come variabile di query string. La risposta dell'API sarà un oggetto JSON:
L'API restituisce tutti i dati associati ai post della categoria con ID uguale a 2 che potranno essere gestiti da qualsiasi applicazione esterna.