Guida approfondita alla creazione e al recupero di endpoint API REST WP personalizzati

Questo post mostrerà come creare endpoint REST WordPress personalizzati e diversi metodi per eseguire le richieste. Ci saranno esempi in PHP, jQuery e vanilla Javascript.

Presumo che tu abbia già familiarità con cos’è l’API REST di WP, ma ecco un breve riassunto. L’API REST di WordPress è un’interfaccia JSON per inviare e ricevere dati dal tuo sito WordPress. È possibile accedere agli endpoint (percorsi/URL specifici) sia esternamente che internamente. WordPress ha già un sacco di endpoint disponibili, ad esempio per recuperare post, categorie, cercare nel sito e altro ancora. Vedi una panoramica degli endpoint WordPress predefiniti qui. Ma gli sviluppatori sono completamente liberi di creare i propri endpoint personalizzati utilizzando questa API, per eseguire azioni o recuperare dati.

Inizieremo con il primo passaggio; che sta creando endpoint personalizzati. Se sei interessato solo a come fare richieste, passa alla seconda parte.

Crea endpoint personalizzati

La registrazione di endpoint personalizzati viene eseguita in PHP. Puoi aggiungere il codice al functions.phpfile di codice del tuo tema o di un plug-in attivo. Crea una funzione agganciata rest_api_inite usa la funzione [register_rest_route](https://developer.wordpress.org/reference/functions/register_rest_route/)()per ogni endpoint che desideri aggiungere.

Come primo parametro register_rest_route()devi fornire uno spazio dei nomi univoco per assicurarti che i tuoi endpoint non siano in conflitto con altri. Usa lo slug del tuo tema o del plugin. È pratica comune quindi includere un /seguito da un numero di versione per il codice. Come esempio userò lo spazio dei nomi awhitepixel/v1. Il secondo parametro è il percorso (che segue lo spazio dei nomi). Infine puoi opzionalmente fornire un array come terzo parametro con opzioni. In questo array puoi ad esempio definire il metodo di richiesta (GET, POST o qualsiasi altro), definire i parametri e, soprattutto, definire la funzione da eseguire quando viene richiesto quell’endpoint.

Come terzo parametro dovresti fornire gli argomenti ‘method’ e ‘callback’ (che è la funzione per gestire i dati dell’endpoint). Per ‘metodo’ puoi impostarli come ‘ GET', 'POST', 'PUT', o qualsiasi altro metodo di richiesta valido (o un array di multipli), ma per questo consiglio di utilizzare le impostazioni predefinite di WordPress. Sono i seguenti:

• WP_REST_Server::READABLE metodo ‘ GET‘
• WP_REST_Server::EDITABLE metodi ‘ POST‘, ‘ PUT‘ e ‘ PATCH‘
• WP_REST_Server::DELETABLE metodo ‘ DELETE‘
• WP_REST_Server::ALLMETHODS tutti i metodi di cui sopra

Creiamo un endpoint personalizzato di base che può essere raggiunto utilizzando le richieste GET:

Alla riga #2abbiamo definito il nostro endpoint personalizzato come ‘ awhitepixel/v1/getsomedata‘. L’URL completo sarebbe l’URL radice dell’API REST di WordPress con prefisso, ovvero <yourdomain>/wp-json. Quindi l’URL completo dell’endpoint sopra sarebbe " <yourdomain>/wp-json/awhitepixel/v1/getsomedata". Alla riga #4abbiamo fornito un nome di funzione come callback, che aggiungeremo a breve.

Quando registri (o modifichi) i percorsi dell’API REST utilizzando register_rest_route(), dovrai svuotare i tuoi permalink affinché funzionino. Puoi farlo visitando Impostazioni> Permalink in amministratore e fai semplicemente clic su Salva.

Non abbiamo ancora definito la funzione di callback, che è la funzione per il codice che gestisce la reazione dell’utilizzo di questo endpoint. Deve restituire una risposta valida REST (in JSON), quindi dovrai restituire qualcosa anche se l’endpoint non dovrebbe restituire dati. È possibile utilizzare la funzione [rest_ensure_response](https://developer.wordpress.org/reference/functions/rest_ensure_response/)()funzione o creare un’istanza di WP_REST_Responseoggetto come ritorno del callback. Come parametro della funzione di callback otteniamo un WP_REST_Requestoggetto che contiene tutte le informazioni sulla richiesta, inclusi eventuali parametri. Creiamo una semplice funzione di callback che invia semplicemente del testo come risposta:

function awhitepixel_rest_route_getsomedata( $request) {
    $response = 'Hello there!';
    return rest_ensure_response( $response );
}

Questo è il modo più semplice per scrivere una richiamata. La funzione rest_ensure_response()assicura che tutti i dati forniti (la stringa) vengano convertiti in una risposta valida REST. Ovviamente vorrai aggiungere più codice qui, per fare qualcosa in WordPress o recuperare e inviare i dati.

Con il codice sopra (registrazione dell’endpoint e della funzione di callback) puoi provare ad andare all’URL nel tuo browser e vedere cosa ottieni. (Ricordati di svuotare i tuoi permalink). Andando su <domain>/wp-json/awhitepixel/v1/getsomedatanel browser verrà mostrata la stringa "Hello there!".

Accettazione dei parametri

È molto comune e utile consentire agli endpoint di accettare parametri. Ad esempio, se il tuo sito ha dati di prodotto, ad esempio, vorresti un endpoint in cui puoi fornire un ID prodotto per ottenere i dati di quel prodotto. Ci sono due modi per farlo. Il modo più comune consiste nell’usare la stringa di query GET (che viene aggiunta dopo l’URL dopo un ?, separata da &nel formato chiave=valore. Ad esempio ‘ <endpoint>/product/?product_id=14‘). In alternativa puoi definire un pattern URL "più carino", in cui i parametri fanno parte del percorso. Ad esempio " <endpoint>/product/14/". Tuttavia, quest’ultimo metodo richiede alcune conoscenze per le espressioni regolari. Quale metodo sceglierai dipende da te, di seguito dimostrerò entrambi.

OTTIENI i parametri

Definire possibili parametri GET per il tuo endpoint sta usando la argschiave ‘ ‘ nel register_rest_route()terzo parametro di ‘. Per ogni parametro che vuoi consentire, definisci il valore della chiave (nell’esempio sopra ‘ product_id‘) e una matrice di opzioni per quel parametro. Come opzioni puoi definire il formato del parametro (se prevede ad esempio un numero o una stringa) e anche decidere se quel parametro è obbligatorio o meno.

Ad esempio, vogliamo consentire al nostro endpoint di accettare ‘ product_id‘ come numero non richiesto.

Se definisci un parametro come true in required, WordPress gestirà il passaggio di una risposta di errore 400. Allo stesso modo se si passa un formato non valido, ad esempio "ciao" come valore a un parametro che si aspetta un numero.

Alla riga #15nella funzione di callback si vede come ottenere il valore del parametro dalla richiesta; utilizzando il metodo nell’oggetto get_param()passato. WP_REST_RequestA titolo di esempio mostrerò risposte diverse a seconda che siano product_idstate fornite o meno (ricordiamo che l’abbiamo definita opzionale). La logica di modificare il tuo codice in base ai parametri forniti dipende completamente da te e dal tuo progetto. Puoi avere meno endpoint che accettano molti parametri o molti più endpoint separati per ogni caso specifico.

Con il codice sopra, riceverò "Hello there!" quando visito <yourdomain>/awhitepixel/v1/getsomedatae "Restituisci i dati del prodotto per l’ID 14" quando vado a <yourdomain>/awhitepixel/v1/getsomedata/?product_id=14.

Parametri come parte del percorso

Se si desidera consentire ai parametri di far parte del percorso anziché GET stringa di query, è possibile farlo. Fornirai quindi un modello regex nel percorso, il secondo parametro per register_rest_route().

La creazione di modelli regex può sembrare piuttosto criptica, ma poiché è un argomento intero, troverai facilmente esempi per casi specifici se lo cerchi su Google. Mostrerò un esempio di definizione di una regex che accetta un numero di qualsiasi lunghezza;

Come puoi vedere nella riga n. 2, ho aggiunto il pattern regex (?P<product_id>[d]+)alla fine. Questo pattern significa che dobbiamo raccogliere un numero( d) di qualsiasi lunghezza( +) e assegnare il valore raccolto nella chiave del parametro product_id. E nella nostra funzione di callback utilizziamo esattamente lo stesso metodo utilizzato durante l’impostazione dei parametri GET; get_param()nell’oggetto WP_REST_Requestfornito alla funzione.

Con il codice sopra (dopo aver scaricato i permalink) possiamo visitare l’URL <yourdomain>/wp-json/awhitepixel/v1/getsomedata/14per ottenere la nostra risposta. Questo metodo si traduce sicuramente in URL "più belli", ma il codice può facilmente diventare più difficile da leggere e correggere i bug. Qualunque metodo tu scelga dipende da te.

Restituire una risposta adeguata

In precedenza ho menzionato brevemente come la funzione di callback debba restituire una risposta REST corretta. Finora abbiamo usato il più semplice rest_ensure_response(). Ma a volte potresti volere un maggiore controllo sul ritorno del tuo endpoint. Ad esempio, potresti voler controllare il codice di stato della risposta HTTP. Supponi di creare un endpoint in cui puoi fornire un ID prodotto e ottenere i dati per quel prodotto. Ma se l’ID prodotto non esiste o se altri parametri creano confusione, potresti voler restituire un codice di stato ad esempio 400 (Richiesta non valida) o 404 (Non trovato). O forse 500 (errore del server). Passare sempre 200 (Success) anche se la richiesta è stata errata può causare problemi alla fine del mittente.

Consiglierei quindi la tua funzione di richiamata che restituisce un WP_REST_Responseoggetto. Con questo oggetto puoi controllare diverse cose, incluso il codice di stato. È più facile di quanto pensi! Nella forma più semplice dovresti creare una nuova istanza di WP_REST_Response, fornire una matrice dei dati da restituire come primo parametro e il codice di stato come secondo parametro. Come esempio:

Nell’esempio sopra memorizziamo il ritorno della awhitepixel_get_product()funzione in una variabile. Questa funzione non esiste e dovresti sostituirla con la funzione che dovrebbe recuperare (o eseguire) le azioni che desideri nel tuo progetto. Ma supponiamo che la funzione restituisca un array vuoto e ciò significa che qualcosa è andato storto (ad esempio il prodotto non esisteva). Potremmo quindi restituire un WP_REST_Responseoggetto con codice di stato 400 e, facoltativamente, un messaggio come dati che spiegano il motivo per cui non è riuscito (riga #5-9). Altrimenti restituiamo i dati con codice di stato 200 Success (riga #10).

Invio di richieste a endpoint (personalizzati).

Passiamo all’altro lato, la parte di invio: come inviare richieste ai nostri endpoint personalizzati. Normalmente invii richieste API REST WP usando Javascript e qui troverai esempi di utilizzo di jQuery, libreria WordPress e Javascript vanilla. È raro, ma possibile, eseguire anche una richiesta REST con PHP, quindi ho incluso anche un esempio di questo.

La prima cosa da tenere presente è che ovviamente è necessario conoscere l’URL completo per inviare una richiesta. Non consiglio di codificare il dominio (prima dell’endpoint) poiché esistono diversi modi per ottenerlo se il tuo Javascript funziona all’interno di WordPress. Nelle versioni precedenti di WordPress è necessario utilizzare [wp_localize_script](https://developer.wordpress.org/reference/functions/wp_localize_script/)()in PHP e passare l’URL REST principale come variabile Javascript globale. Ma gli esempi seguenti mostrano un modo più nuovo e migliore per ottenere l’URL radice REST del sito WordPress.

Un’altra cosa da notare è che per il tuo progetto probabilmente avvolgeresti le richieste come risultato di qualche azione. Per semplificare le cose, sto preparando tutte le richieste al DOM, quindi dovresti assicurarti di racchiudere il codice della richiesta, ad esempio come risultato di un visitatore che fa clic su un pulsante.

Usando jQuery

Se hai e vuoi usare la libreria jQuery, puoi usare la sua [$.ajax](https://api.jquery.com/jquery.ajax/)()funzione.

Ma prima una nota sulle dipendenze del tuo file Javascript. Ovviamente il tuo script avrebbe bisogno 'jquery'di una dipendenza per accodarlo. Ma per accedere facilmente all’URL radice REST di WordPress, aggiungi un’altra dipendenza; ‘wp-api-richiesta’. Ciò garantisce che la variabile Javascript wpApiSettings.rootsia disponibile e contenga l’URL radice dell’API REST. Ecco un esempio di come accodare lo script per illustrare questa dipendenza;

add_action( 'wp_enqueue_scripts', function() {
    wp_enqueue_script(
        'awp-javascript-wp-rest', 
        get_stylesheet_directory_uri(). '/assets/js/javascript_wp_rest.js', 
        [ 'jquery', 'wp-api-request' ], 
        null, 
        true
    );
} );

La linea #5è quella interessante; dove definiamo sia jQuery che wp-api-requestcome dipendenza. Quindi nel nostro file Javascript possiamo eseguire una richiesta API REST WP in questo modo:

( function( $) {
    // Send request
    $.ajax( {
        url: wpApiSettings.root + 'awhitepixel/v1/getsomedata',
        method: 'GET',
        data: {
            product_id: 14
        },
        success: function( data) {
            console.log( data );
        }
    } );
} )( jQuery );

Questo è il più semplice possibile. Usiamo $.ajax()per inviare una richiesta GET all’URL definito. Come URL utilizziamo wpApiSettings.rootper ottenere l’URL radice dell’API REST e quindi aggiungiamo l’endpoint desiderato dopo di esso; nel nostro caso l’endpoint personalizzato che abbiamo creato in precedenza. Facoltativamente possiamo passare i parametri in ‘dati’. L’esempio sopra passa product_idcon il valore 14 all’endpoint. Infine nella successfunzione riceviamo la richiesta (riuscita) come parametro e siamo liberi di farne quello che vogliamo. Nell’esempio sopra lo stampiamo semplicemente sulla console.

Utilizzo della libreria di WordPress (non jQuery)

Se il tuo sito WordPress non ha, o può, utilizzare la libreria jQuery, puoi utilizzare la libreria Javascript di WordPress per eseguire facilmente una richiesta API REST. La funzione è apiFetchdisponibile nello spazio dei wpnomi globale di WordPress. wp.apiFetch()è un metodo wrapper per la fetch()funzione standard del browser (dimostrata di seguito).

Il nostro Javascript avrà bisogno della dipendenza ‘wp-api’ per poter usare wp.apiFetch(). Ad esempio potremmo accodare lo script in questo modo:

add_action( 'wp_enqueue_scripts', function() {
    wp_enqueue_script(
        'javascript-wp-rest', 
        get_stylesheet_directory_uri(). '/assets/js/javascript_wp_rest.js', 
        [ 'wp-api' ], 
        null, 
        true
    );
} );

Troverai la dipendenza critica alla riga #5. Con questo ci siamo assicurati che il nostro file Javascript fosse wp.apiFetch()disponibile. Ecco un esempio di base per usarlo:

Tieni presente che la linea #9-13è solo logica per eseguire la funzione dopo che DOM è pronto.

Un vantaggio dell’utilizzo wp.apiFetch()rispetto al normale fetch()è che possiamo usare ‘path’ che richiede solo l’endpoint, invece di ‘url’ che richiede l’URL completo. Un altro vantaggio è che la prima "catena" di .then()restituisce i dati già formattati JSON. Quando usi l’originale .fetch()hai bisogno di più catene ".then()". Dai un’occhiata al prossimo esempio ("Using vanilla Javascript") per vedere cosa intendo.

Tieni presente che fetch()(e di conseguenza wp.apiFetch()) non fornisce un modo "pulito" per passare i parametri. Avremo bisogno di costruire manualmente la stringa di query GET in ‘percorso’, come ho fatto sopra: '../getsomedata?product_id=14'.

Se sei interessato a come incorporare wp.apiFetche personalizzare gli endpoint in un blocco Gutenberg, ho scritto un tutorial separato su questo:

Utilizzo di Javascript vaniglia

Come ultimo esempio di metodi Javascript per inviare richieste all’API REST di WP esiste un modo puro, non WordPress, che utilizza fetch(). Tieni presente che utilizzo la variabile globale di WordPress per ottenere l’URL radice REST. Se stai aggiungendo questo script al di fuori di WordPress, probabilmente dovrai codificare l’URL completo.

Dal momento che voglio ancora accedere alla variabile globale per l’URL radice WP REST, aggiungo 'wp-api-request'dipendenza alla mia funzione di accodamento Javascript, in questo modo:

add_action( 'wp_enqueue_scripts', function() {
    wp_enqueue_script(
        'awp-javascript-wp-rest', 
        get_stylesheet_directory_uri(). '/assets/js/javascript_wp_rest.js', 
        [ 'wp-api-request' ], 
        null, 
        true
    );
} );

E poi nel nostro file Javascript un esempio più semplice sarebbe:

Come accennato in precedenza ("Utilizzo della libreria di WordPress") .fetch()non supporta un modo semplice e pulito di fornire parametri. Quindi dovrai creare manualmente la stringa di query ("? product_id=14") nell’URL.

Tieni presente che la richiesta di recupero non restituisce direttamente i dati, ma restituisce una promessa. Ecco perché dobbiamo concatenare ” .then()" prima di poter gestire i dati. Se questo ti suona sconosciuto, ti consiglio di cercare come lavorare fetch(): ci sono molte spiegazioni ed esempi su Google che possono spiegarlo meglio di me.

Se vuoi controllare il codice di stato della risposta REST alla tua richiesta, puoi farlo in questo modo;

Nell’esempio sopra nella registrazione di endpoint personalizzati, ho menzionato come è possibile restituire codici di stato HTTP diversi. Il codice precedente mostra un esempio su come controllare il codice di stato della risposta, disponibile nella .statusproprietà dell’oggetto restituito. Nell’esempio sopra, controllo se il codice di stato è diverso da 200 (Success) at line #5. Solo se il codice di stato era 200 converto il ritorno dei dati della promessa in JSON (line #9).

Usando PHP

È meno comune, ma è comunque possibile, eseguire la richiesta REST internamente in WordPress utilizzando PHP. Ecco come.

Per inviare una richiesta API REST WP in PHP, creiamo un WP_REST_Requestoggetto (esattamente come quello passato alla nostra funzione di callback in precedenza in questo post). In questa istanza dell’oggetto definiamo il metodo (ad es. GET) e il percorso dell’endpoint. Opzionalmente possiamo anche aggiungere parametri. Quindi utilizziamo la funzione di WordPress [rest_do_request](https://developer.wordpress.org/reference/functions/rest_do_request/)()con questa istanza di richiesta. Infine otteniamo la risposta con la [response_to_data](https://developer.wordpress.org/reference/classes/wp_rest_server/response_to_data/)()funzione disponibile nella WP_REST_Server'classe s.

La chiamata di funzione set_query_params()(line #3-5) è facoltativa e necessaria solo se si desidera passare parametri. Seguendo il thread rosso in questo post, includerò un esempio di passaggio del parametro della funzione alla chiave del parametro REST product_id.

La linea #6è dove inviamo la richiesta. E alla riga #7restituiamo i dati della risposta. Quindi, se dovessimo chiamare questa funzione PHP, ad esempio awp_do_php_rest_request( 14 ), otterremmo la risposta che abbiamo definito in quell’endpoint (un array con una stringa se usi ancora lo stesso esempio dell’inizio di questo post).