Nella lezione precedente abbiamo introdotto la Rest API di WordPress e abbiamo mostrato la risposta ad una prima generica richiesta:
OPTIONS https://example.com/wp-json/wp/v2/posts
A questa richiesta l'API risponde con un oggetto JSON contenente i dati disponibili sugli ultimi articoli pubblicati nel blog.
Ma non è necessario richiedere sempre tutti i dati. La Rest API, infatti, fornisce alcuni parametri globali, disponibili per tutte le risorse, che permettono di avere il controllo sui dati che saranno inclusi nella risposta.
Il parametro _field
Il parametro _field
permette di stabilire quali campi dovranno essere compresi nella risposta, permettendo di ricevere solo i dati rilevanti al caso specifico. Evitando quindi l'esecuzione di query che consumano una quantità non necessaria di risorse, oltre che il download e il parsing di oggetti JSON di grandi dimensioni.
Il parametro _fields
accetta un elenco di elementi separati da virgola:
/wp/v2/posts?_fields=id,title,link
Oppure, nel caso in cui i pretty permalink non siano abilitati, si può utilizzare la sintassi degli array in una query string:
/wp/v2/posts?&_fields[]=id&_fields[]=title&_fields[]=link
La proprietà _links
Molte risorse includono link a risorse correlate. Ad esempio, un post può contenere un link a un post genitore, ai commenti lasciati dagli utenti e alla pagina dell'autore. La REST API dispone di parametri che permettono di recuperare i link a queste risorse, riducendo il numero di richieste HTTP necessarie.
I link alle risorse correlate sono raggruppati per "relazione" sotto la proprietà _links
della risposta JSON.
Ecco un esempio:
[
{
...
"_links": {
"self": [
{
"href": "https://example.com/wp-json/wp/v2/posts/1551"
}
],
"collection": [
{
"href": "https://example.com/wp-json/wp/v2/posts"
}
],
"about": [
{
"href": "https://example.com/wp-json/wp/v2/types/post"
}
],
"author": [
{
"embeddable": true,
"href": "https://example.com/wp-json/wp/v2/users/1"
}
],
},
...
}
]
Il parametro _embed
Il parametro _embed
stabilisce che la risposta del server deve includere le risorse incorporate.
Questo parametro non richiede l'assegnazione di un valore e può essere utilizzato semplicemente aggiungendo ?_embed
alla query string. Tuttavia è possibile assegnare al paramentro _embed
uno o più valori per stabilire in modo granulare quali risorse debbano essere incluse nella risposta. La query riportata di seguito restituirà i dati relativi ad autore e immagine di anteprima dei post:
https://example.com/wp-json/wp/v2/posts?_embed=author,wp:featuredmedia
Nell'esempio che segue, invece, vengono richiesti i termini delle tassonomie:
https://example.com/wp-json/wp/v2/posts?_embed=author,wp:term
In modalità embed, la risposta conterrà una chiave _embedded
sotto la quale saranno rese disponibili le risorse collegate (se il flag embeddable
è impostato su true
).
Quello che segue è un frammento di risposta in modalità embedded:
[
{
"id": 1551,
"date": "2022-02-12T21:10:20",
"date_gmt": "2022-02-12T20:10:20",
"modified": "2022-02-20T10:21:35",
"modified_gmt": "2022-02-20T09:21:35",
"slug": "post-di-esempio",
"status": "publish",
"type": "post",
"content": {...},
"excerpt": {...},
"_links": {...},
"_embedded": {
"author": [...],
"wp:featuredmedia": [...],
"wp:term": [...]
}
}
]
Questo è quanto occorre sapere per accedere alla Rest API di WordPress, recuperare i dati dei post e importarli in un'applicazione React per la visualizzazione.
Per una descrizione più dettagliata delle richieste e delle risposte dell'API, si veda il manuale sulla REST API di WordPress.org, i concetti chiave e il riferimento dell'API.
Ora che sappiamo come comporre la richiesta e come sono strutturate le risposte, nella prossima lezione muoveremo un passo avanti con la prima configurazione di un'applicazione React.