API REST di WP: Meccanismi Interni e Personalizzazione

Italian (Italiano) translation by Piergiorgio Sansone (you can also view the original English article)

Nella parte precedente della serie, abbiamo imparato la creazione, l'aggiornamento e l'eliminazione di contenuti da remoto tramite l'API REST di WP. Permettendoci di creare applicazioni indipendenti dalla piattaforma che opera senza soluzione di continuità con un WordPress alimentato da back-end, fornendo una ricca esperienza per l'utente.

In questa parte della serie, daremo un'occhiata ai meccanismi interni dell'API REST di WP e come lavorano insieme per alimentare le API. Dopo di che, impareremo a modificare le risposte del server per gli endpoint predefiniti per includere campi personalizzati.

Per essere precisi, nell'articolo attuale, ci impegniamo a:

conoscere i metodi dell'API REST WP e le classi interne
modificare la risposta del server per endpoint predefiniti
imparare a fare campi personalizzati modificabili

Iniziamo col dare un'occhiata ai meccanismi interni dell'API REST di WP.

Le classi interne e i metodi dell'API REST WP

Le classi nell'API REST WP possono essere divise nelle due categorie seguenti:

Classi di infrastruttura: Sono le classi fondamentali responsabili a tenere insieme l'API. Queste non eseguono trasformazione di dati.
Classi di endpoint: queste classi sono responsabili per l'esecuzione di operazioni CRUD sulle risorse come post, pagine, utenti, commenti, ecc.

Diamo un'occhiata alle singole classi di ciascuna delle due categorie di cui sopra.

Classi di infrastruttura

Le tre classi di infrastruttura che insieme alimentano l'API REST sono le seguenti :

WP_REST_Server
WP_REST_Request
WP_REST_Response

WP_REST_Server

Questa è la classe principale dell'API REST di WP che implementa il server di REST registrando percorsi, servendo le richieste e preparando le risposte. Formatta i dati da passare ai client e in caso di errore, prepara l'errore includendo il corpo di codice e messaggio di errore. Inoltre, controlla l'autenticazione.

Abbiamo lavorato molto con l'endpoint indice /wp-json per il controllo di tutte le funzionalità e i percorsi supportati per un sito. Il metodo get_index(), che è responsabile del recupero dell'index del sito, si trova anche in questa classe.

Per servire le richieste e preparare le risposte, la classe WP_REST_Server utilizza rispettivamente le classi WP_REST_Request e WP_REST_Response.

WP_REST_Request

La classe WP_REST_Request implementa l'oggetto di richiesta per l'API REST di WP. Contiene i dati della richiesta come intestazioni e il corpo della richiesta e viene passato alla funzione di callback dalla classe WP_REST_Server. Inoltre controlla se sono validi i parametri che vengono passati attraverso la richiesta ed esegue una pulizia dei dati quando necessario.

WP_REST_Response

La classe WP_REST_Response, come suggerisce il nome, implementa l'oggetto response. Contiene dati necessari come codice di stato della risposta e il corpo della risposta.

Ed ora diamo un'occhiata alle classi dell'endpoint.

Classi di endpoint

Le classi di endpoint nell'API REST WP sono responsabili per l'esecuzione di operazioni CRUD. Queste classi includono WP_REST_Posts_Controller, WP_REST_Taxonomies_Controller, WP_REST_Users_Controller, ecc. Tutte queste classi di endpoint estendendono una sola classe astratta WP_REST_Controller che fornisce un modello coerente per la modifica dei dati.

La classe WP_REST_Controller include metodi quali get_Item (), create_item(), update_item(), delete_item(), ecc., per l'esecuzione di operazioni CRUD. Questi metodi devono essere sovrascritti da sottoclassi implementando la propria astrazione per il recupero, la creazione, l'aggiornamento e modifica dei dati.

Troverete maggiori informazioni su queste classi e loro metodi interni nella documentazione ufficiale.

Avendo imparato a conoscere le classi interne dell'API REST di WP, diamo un'occhiata a come possiamo modificare le risposte del server per gli endpoint predefiniti per includere campi personalizzati.

Modificare le risposte del Server

Nella sezione precedente, abbiamo esaminato le classi interne e i metodi su cui l'API si basa . Insieme queste classi e metodi guidano l'API nel suo complesso e consentono agli sviluppatori di estendere l'API per diversi scenari e casi d'uso.

L'API REST di WP espone i dati in modo prevedibile. Questo include diverse risorse come post, post meta, le pagine e gli utenti, insieme alle loro proprietà standard. Ma questi dati non sempre sono conformi alle esigenze di ogni singolo sito di WordPress o utente. Di conseguenza, l'API REST di WP fornisce un modo per modificare i dati restituiti dal server per ciascuna delle rotte predefinite.

Il metodo register_rest_field() fornisce un modo per aggiungere o aggiornare i campi nella risposta per un oggetto. Tuttavia, la modifica di un campo da una risposta non è mai incoraggiata dall'API poiché potrebbe comportare problemi di compatibilità per i client che si aspettano una risposta dal server standard. Così, se avete bisogno di modificare un campo, dovreste considerare di duplicare il campo con il valore desiderato.

Allo stesso modo, l'eliminazione di un campo predefinito è altamente sconsigliato per la ragione che un client potrebbe aspettarselo. Se avete bisogno di un piccolo sottoinsieme della risposta restituita dal server, dovreste creare ulteriori contesti oltre i contesti predefiniti come vista o modifica.

Tuttavia, possiamo, in modo sicuro aggiungere un campo per la risposta restituita dal server per uno o più oggetti. Questi campi possono contenere qualsiasi valore compreso tra meta post o utente su qualsiasi altro valore arbitrario.

Nella sezione successiva, lavoreremo con il metodo register_rest_field() per aggiungere campi personalizzati per la risposta restituita dal server per l'oggetto del post.

Lavorando con il `register_rest_field()` metodo.

Come accennato in precedenza, il metodo register_rest_field() può essere utilizzato per aggiungere o aggiornare i campi nella risposta restituita dal server. Questo metodo accetta tre argomenti:

$object_type
$attribute
$args

L'argomento di $object_type può essere una stringa o una matrice contenente i nomi di tutti gli oggetti che si desidera aggiungere nel campo. Questi oggetti possono essere post, termine, commento, utente, ecc. Se abbiamo bisogno di aggiungere un campo personalizzato a un tipo di post personalizzato, l'argomento di $object_type sarebbe il nome di tipo post.

L'argomento di $attribute è il nome del campo personalizzato. Questo nome apparirà nella risposta del server come una chiave insieme al suo valore.

La matrice di $args è un array associativo che può contenere i seguenti tre tasti:

$get_callback
$update_callback
$schema

I valori delle prime due chiavi sono i nomi dei metodi che vengono utilizzati per ottenere o aggiornare il valore del campo personalizzato. L'ultima chiave di $schema definisce il metodo o la variabile che viene utilizzata per definire lo schema per il campo personalizzato.

Tutti i tasti di cui sopra sono facoltativi, ma se non vengono aggiunti, la funzionalità non verrà aggiunta. Per esempio, se si definisce la chiave di $get_callback ma non la chiave di $update_callback, si aggiungerà la funzionalità di recupero ma la funzionalità di aggiornamento non sarà aggiunta. Se si omette la chiave $get_callback, il campo non verrà aggiunto alla risposta a tutti.

Il metodo register_rest_field() funziona modificando la variabile $wp_rest_additional_fields. Questa variabile matrice contiene i campi registrati dai tipi di oggetti da restituire nella risposta dal server. Ogni volta che un campo viene registrato con il metodo di register_rest_field(), esso viene aggiunto alla variabile $wp_rest_additional_fields. Tuttavia, modificare manualmente la variabile $wp_rest_additional_fields è fortemente sconsigliato.

Aggiunta di campi personalizzati per la risposta

Avendo familiarizzato con il metodo di register_rest_field(), possiamo ora modificare la risposta per l'oggetto del post. Un tipico caso d'uso qui sarebbe l'aggiunta di un campo nome visualizzato dell'autore, che è comunemente necessaria quando viene pubblicata la lista dei post su una pagina index. Poiché la risposta standard non include questo campo, possiamo utilizzare il metodo register_rest_field() per includerlo nella risposta.

Iniziamo creando un semplice plugin. Quindi, create una nuova cartella denominata rest-response-modifier nella directory /wp-content/plugins. Creare un file index. php vuoto e incollare la seguente definizione di plugin:

<?php
/**
 * Plugin Name: REST Response Modifier
 * Description: A very simple plugin for development and testing purpose to modify the response of the REST API plugin.
 * Author: Bilal Shahid
 * Author URI: http://imbilal.com
 */

Il metodo register_rest_field() deve essere registrato nell'azione rest_api_init. Quindi, creiamo una funzione denominata bs_add_custom_rest_fields() e associamola al gancio rest_api_init:

<?php
add_action( 'rest_api_init', 'bs_add_custom_rest_fields' );

function bs_add_custom_rest_fields() {
    
}

Notate che l'apertura tag PHP <?php non è necessaria qui, ma l'ho inclusa cosi la sintassi è evidenziata correttamente.

All'interno della funzione bs_add_custom_rest_fields(),possiamo utilizzare il metodo register_rest_field() per includere un campo per il nome dell'autore:

function bs_add_custom_rest_fields() {
    // schema for the bs_author_name field
    $bs_author_name_schema = array(
        'description'   => 'Name of the post author',
        'type'          => 'string',
        'context'       =>  array( 'view' )
    );
    
    // registering the bs_author_name field
    register_rest_field(
        'post',
        'bs_author_name',
        array(
            'get_callback'      => 'bs_get_author_name',
            'update_callback'   => null,
            'schema'            => $bs_author_name_schema
        )
    );
}

Come accennato nella sezione precedente, il primo argomento nel metodo register_rest_field() è il nome dell'oggetto per il quale stiamo modificando la risposta. Poiché abbiamo bisogno di modificare la risposta per l'oggetto del post,passiamo lo stesso come primo argomento.

Il secondo argomento nel codice precedente è il nome del campo che apparirà nella risposta. È sempre una buona pratica dare un prefisso al nome di un campo personalizzato nella risposta, per assicurarsi la massima compatibilità con le versioni e che non venga sovrascritto in futuro da altri plugin. Quindi, passiamo bs_author_name nel secondo argomento come $attribute del campo personalizzato.

Il terzo e ultimo argomento nel codice precedente è una matrice per i metodi di callback e lo schema. Questa matrice contiene il nome dei metodi di callback per il recupero e l'aggiornamento del campo personalizzato nelle chiavi rispettivamente $get_callback e $update_callback . Passiamo la funzione bs_get_author_name come metodo di recupero callback . Definiremo questa funzione a breve.

Per la chiave di $update_callback, dobbiamo passare null poiché questo è un campo di sola lettura e non abbiamo bisogno di aggiornare il nome dell'autore per un post.

Per la chiave di $schema, si passa una matrice denominata $bs_author_name_schema. Questa matrice contiene varie proprietà per il campo come il tipo di dati, il contesto e la descrizione.

L'unica cosa che dobbiamo definire ora è la funzione di bs_get_author_name() che verrà utilizzata come il metodo $get_callback per il nostro campo personalizzato. Di seguito è riportato il codice per questa funzione:

/**
 * Callback for retrieving author name
 * @param  array            $object         The current post object
 * @param  string           $field_name     The name of the field
 * @param  WP_REST_request  $request        The current request
 * @return string                           The name of the author
 */
function bs_get_author_name( $object, $field_name, $request ) {
    return get_the_author_meta( 'display_name', $object['author'] );
}

Il metodo $get_callback riceve tre argomenti per le seguenti operazioni:

$object: l'oggetto corrente. Nel nostro caso, è il post corrente.
$field_name: il nome del campo personalizzato da aggiungere.
$request: l'oggetto request.

Stiamo utilizzando la proprietà $author dell'argomento $object che contiene l'id dell'autore del post. E utilizzando la funzione di get_the_author_meta(), dobbiamo recuperare e restituire il nome visualizzato dell'autore per il post corrente.

Ora che il campo è stato registrato, possiamo inviare una richiesta GET la via /wp/v2/posts per vedere se funziona correttamente:

Ecco la risposta nel Postman:

Questo campo personalizzato appena registrato apparirà anche nella risposta del server, insieme con il relativo schema, quando inviamo una richiesta OPTIONS per il percorso di /wp/v2/posts:

Quindi un campo personalizzato per la proprietà di nome autore è stato registrato correttamente. Ma questo campo è di sola lettura come non possiamo aggiornarlo inviando una richiesta POST. Nella sezione seguente, registreremo un campo modificabile per numero di visualizzazioni di post.

Registrazione un campo modificabile

Ora registreremo un campo personalizzato per il numero di visualizzazioni di post. Ci occuperemo solo dell'effettiva registrazione del campo con WP REST API, tralasciando l'implementazione per incrementare il contatore.

Di seguito c'è il codice per bs_post_views il campo personalizzato di registrazione insieme al relativo schema:

// schema for bs_post_views field
$bs_post_views_schema = array(
    'description'   => 'Post views count',
    'type'          => 'integer',
    'context'       =>	array( 'view', 'edit' )
);

// registering the bs_post_views field
register_rest_field(
    'post',
    'bs_post_views',
    array(
        'get_callback'      => 'bs_get_post_views',
        'update_callback'   => 'bs_update_post_views',
        'schema'            => $bs_post_views_schema
    )
);

Il codice è simile a quello che abbiamo scritto nella sezione precedente tranne per il fatto che ora include un metodo di callback bs_update_post_views per la chiave $update_callback. Questa funzione è responsabile dell'aggiornamento del valore del campo.

La proprietà $context nella matrice dello schema $bs_post_views_schema include due valori per visualizzazione e modifica. Inclusione del valore di modifica nell'argomento $context assicura che il campo bs_post_views vienga restituito nella risposta del server dopo che è stato aggiornato.

I metodi di callback di recupero e aggiornamento sono i seguenti:

/**
* Callback for retrieving post views count
* @param  array             $object         The current post object
* @param  string            $field_name     The name of the field
* @param  WP_REST_request   $request        The current request
* @return integer                           Post views count
*/
function bs_get_post_views( $object, $field_name, $request ) {
    return (int) get_post_meta( $object['id'], $field_name, true );
}

/**
* Callback for updating post views count
* @param  mixed     $value          Post views count
* @param  object    $object         The object from the response
* @param  string    $field_name     Name of the current field
* @return bool|int
*/
function bs_update_post_views( $value, $object, $field_name ) {
    if ( ! $value || ! is_numeric( $value ) ) {
        return;
    }

    return update_post_meta( $object->ID, $field_name, (int) $value );
}

Il codice è abbastanza semplice in quanto utilizza i metodi get_post_meta() e update_post_meta per recuperare e aggiornare i valori rispettivamente.

Il metodo bs_get_post_views() prima recupera il valore di meta per il tasto meta bs_post_views e si getta in un valore integer prima di restituirlo.

Il metodo di callback passato in $update_callback riceve tre argomenti per le seguenti operazioni:

$value: il nuovo valore per il campo.
$object: oggetto corrente dalla risposta.
$field_name: il nome del campo in fase di aggiornamento.

Nel metodo bs_update_post_views(), controlliamo prima se il valore passato non è vuoto ed è un valore numerico. In caso contrario, ci ritorno senza fare nulla.

Se il valore è numerico, si passa alla funzione update_post_meta che salva nel database dopo la fusione in un valore inter valido.

Dopo aver registrato correttamente il campo, testiamo inviando una richiesta GET:

1	$ GET /wp/v2/posts

Di seguito è una risposta di esempio per la richiesta di cui sopra:

Come possiamo vedere nell'immagine sopra, il valore corrente del campo di bs_post_views è 0 per un determinato post. Infatti, il metodo get_post_meta() restituisce una stringa vuota poiché non poteva trovare un valore di meta per il tasto meta bs_post_views e cast dei tipi in una stringa vuota in un valore integer in PHP risultati in 0.

Possiamo aggiornare il campo di bs_post_views inviando una richiesta POST per l'endpoint /wp/v2/posts/<id>. Il corpo JSON per la richiesta è il seguente:

1	{
2	"bs_post_views": 4050
3	}

Se la richiesta ha esito positivo, il server restituisce un codice di stato 200 - OK insieme all'oggetto post aggiornato che include anche il campo di bs_post_views:

Il campo personalizzato bs_post_views ora è aggiornato.

Notate che abbiamo inviato un corpo JSON attraverso la richiesta per aggiornare il campo. Il corpo JSON incluso il nome del campo — bs_post_views — con valore integer di 4050. Se si tenta di inviare un valore non numerico, dire "abc1234", il campo non verrà aggiornato dal momento che abbiamo una condizione di verifica di un valore numerico nel metodo di callback bs_update_post_views().

Di seguito è riportato il codice sorgente completo per il plugin:

<?php
/**
 * Plugin Name: REST Response Modifier
 * Description: A very simple plugin for development and testing purpose to modify the response of the REST API plugin.
 * Author: Bilal Shahid
 * Author URI: http://imbilal.com
 */

add_action( 'rest_api_init', 'bs_add_custom_rest_fields' );

/**
 * Function for registering custom fields
 */
function bs_add_custom_rest_fields() {
    // schema for the bs_author_name field
    $bs_author_name_schema = array(
        'description'   => 'Name of the post author',
        'type'          => 'string',
        'context'       =>	array( 'view' )
    );
    
    // registering the bs_author_name field
    register_rest_field(
        'post',
        'bs_author_name',
        array(
            'get_callback'      => 'bs_get_author_name',
            'update_callback'   => null,
            'schema'            => $bs_author_name_schema
        )
    );
    
    // schema for bs_post_views field
    $bs_post_views_schema = array(
        'description'   => 'Post views count',
        'type'          => 'integer',
        'context'       =>	array( 'view', 'edit' )
    );
    
    // registering the bs_post_views field
    register_rest_field(
        'post',
        'bs_post_views',
        array(
            'get_callback'      => 'bs_get_post_views',
            'update_callback'   => 'bs_update_post_views',
            'schema'            => $bs_post_views_schema
        )
    );
}

/**
 * Callback for retrieving author name
 * @param  array            $object         The current post object
 * @param  string           $field_name     The name of the field
 * @param  WP_REST_request  $request        The current request
 * @return string                           The name of the author
 */
function bs_get_author_name( $object, $field_name, $request ) {
    return get_the_author_meta( 'display_name', $object['author'] );
}

/**
 * Callback for retrieving post views count
 * @param  array            $object         The current post object
 * @param  string           $field_name     The name of the field
 * @param  WP_REST_request  $request        The current request
 * @return integer                          Post views count
 */
function bs_get_post_views( $object, $field_name, $request ) {
    return (int) get_post_meta( $object['id'], $field_name, true );
}
/**
 * Callback for updating post views count
 * @param  mixed    $value          Post views count
 * @param  object   $object         The object from the response
 * @param  string   $field_name     Name of the current field
 * @return bool|int
 */
function bs_update_post_views( $value, $object, $field_name ) {
    if ( ! $value || ! is_numeric( $value ) ) {
        return;
    }

    return update_post_meta( $object->ID, $field_name, (int) $value );
}

Questo è tutto per modificare le risposte del server per gli endpoint dell'API predefinito. Abbiamo appena scalfito la superficie per modificare l'API REST in quanto offre una maggiore flessibilità rispetto alla modifica solo le risposte del server. Questo include l'aggiunta del supporto per il tipo di contenuto personalizzato tramite controller personalizzato e gli spazi dei nomi e percorsi personalizzati per l'esposizione e la modifica dei dati di registrazione. Cercheremo di coprire questi argomenti più avanzati nei prossimi articoli .

E' solo l'inizio...

Qui concludiamo il nostro viaggio di presentarci all'API REST di WP. In questa serie, abbiamo coperto piuttosto essenziali concetti come metodi di autenticazione e recupero, la creazione e l'aggiornamento dei dati. In quest'ultima parte della serie, abbiamo brevemente esaminato le classi interne dell'API REST di WP e quindi imparato a modificare le risposte del server per gli endpoint predefiniti.

Non è mai stato lo scopo di questa serie coprire ogni aspetto dell'API REST WP — infatti, non potrà mai essere raggiunto in una singola serie. Ma piuttosto, lo scopo di questa serie era di arrivare fino a qui ed eseguire questa fantastica aggiunta ed incoraggiarvi a giocare e sperimentare per conto vostro. Spero che abbiate trovato soddisfacente questa serie e che abbia raggiunto gli obbiettivi sperati.