Guida alla configurazione dei custom endpoint WordPress: scopriamo come utilizzarli

Cosa sono le api rest e perchè dovresti conoscerle

Se sei un appassionato di sviluppo web, avrai sicuramente sentito parlare delle API REST. Ma cosa sono esattamente? Un’API, ovvero Interfaccia di Programmazione delle Applicazioni, rappresenta un insieme di regole che stabilisce come applicazioni o dispositivi possono comunicare tra loro. L’API REST, un’evoluzione basata sui principi architetturali di REST (Rappresentational State Transfer), ne è una versione particolarmente flessibile e dinamica, spesso definita come API RESTful.

L’intuizione geniale di Roy Fielding, informatico visionario, introdusse per la prima volta la REST nel 2000 tramite la sua tesi di dottorato. Questa architettura concede agli sviluppatori un’elevata flessibilità e libertà nel progettare interazioni tra sistemi. Questo approccio è diventato il metodo preferito per connettere componenti e applicazioni in un’architettura a microservizi, grazie alla sua scalabilità e adattabilità.

Nel mondo delle API, il fulcro è costituito dai principi di progettazione REST. Questi principi stabiliscono le fondamenta per la creazione di interazioni tra applicazioni e servizi. Ad esempio, un’API funziona come una sorta di intermediario che consente a un’applicazione di accedere a risorse all’interno di un’altra. Da un lato, c’è il “client” che richiede l’accesso, mentre dall’altro c’è il “server” che ospita la risorsa. Questa divisione netta e indipendenza tra client e server è uno dei pilastri fondamentali del design REST.

Le API REST si differenziano da altre tecnologie, come SOAP o XML-RPC, proprio per la loro flessibilità. Possono essere sviluppate con diversi linguaggi di programmazione e supportano una varietà di formati dati. Tutto ciò che serve è rispettare i principi chiave di progettazione REST, noti come vincoli architetturali. Questi vincoli includono un’interfaccia uniforme per le richieste, il disaccoppiamento tra client e server, la condizione di “statelessness” (senza stato), la cacheabilità, l’architettura a strati e persino la possibilità di includere codice eseguibile su richiesta.

In questo articolo ti guideremo attraverso i dettagli operativi di queste potenti risorse digitali. Imparerai come le API REST utilizzano richieste HTTP per eseguire operazioni standard sui dati, dal login all’eliminazione di un utente, all’interno di WordPress. Scoprirai anche l’importanza delle intestazioni e dei parametri delle richieste, nonché le migliori pratiche per garantire sicurezza e affidabilità nell’era delle API REST.

Perchè utilizzare wordpress ed i custom endpoint?

Ecco alcune informazioni sull’utilizzo di WordPress nel mondo:

Ed ecco un elenco dei siti più popolari ad alto traffico che lo utilizzano:

• Microsoft.com
• WordPress.org
• Vimeo.com
• WordPress.com
• Mozilla.org
• Digicert.com
• Gravatar.com
• Nih.gov
• Apache.org
• Soundcloud.com

Fonte: https://w3techs.com/technologies/details/cm-wordpress

WordPress REST API

Iniziamo con definire di cosa si tratta. È anche uno strumento per la creazione di percorsi ed endpoint personalizzati che ci permette quindi di realizzare soluzioni API REST.

URL DOCUMENTAZIONE:
https://developer.wordpress.org/rest-api/extending-the-rest-api/adding-custom-endpoints/

Nel nostro esempio vedremo come creare 2 custom endpoint:

• Autenticazione di un utente
• Cancellazione di un utente

Inserimento un controllo sugli accessi utilizzando le permission_callback così da vincolarne l’accesso solo agli utenti autorizzati. Per questo tipo di controllo utilizzeremo una versione semplificata di un JWT (JSON Web Token).

Installazione wp e attivazione application password

Primo passo è avviare un’installazione WP nel nostro caso locale e attivare per gli utenti la possibilità di creare le application password.
Le application password ci permetterano di implementare il controllo sugli accesi ed è un metodo standard di WordPress per proteggere l’accesso non autorizzato agli endpoint.

Di default in un ambiente locale di test non è possibile creare Application Password. Per farlo andrà aggiunta una configurazione al file wp-config.php.

define( 'WP_ENVIRONMENT_TYPE', 'local' );

Configurazione e base64 encoding

A questo punto saremo in in grado di creare un’application password dal backend di WordPress. Il pannello dell’immagine si trova in basso nella scheda utente:

In questo modo verrà egenerata una password che utilizzeremo per generare la versione encodata con base64 per la basic Authentication. Questo ci permetterà di aggiungere nell’header della chiamata all’endpoint username e password per accedere ala risorsa.

Ecco il codice PHP:

$str = 'username:password_generata';
echo base64_encode($str);
es: YmVld2ViOnRMZjAgQW9ubiBGaFhDIEtnelogcFVSRSB1bjIx

Creo il child theme ed il file custom-endpoint.php

Includo nel file functions.php il file appena creato

// Faccio l'import del file in functions.php
require_once( 'library/custom-endpoint.php' );

Finalmente possiamo creare il nostro primo endpoint:

Creo l’endpoint per il login di un utente

// login utilizzando le REST API
add_action(
    'rest_api_init',
    function(){
        register_rest_route(
            'api',
            'login',
            array(
                'methods' => 'POST',
                'callback' => 'login',
                // RENDO LA CALLBACK ACCESSIBILE 
                // SOLO PER GLI UTENTI CHE POSSONO EDITARE I POST
                'permission_callback' => function () {
                    return current_user_can( 'edit_others_posts' );
                }
            ),
        );
    }
);

Per la descrizione dei parametri potete far riferimento alla documentazione ufficiale https://developer.wordpress.org/rest-api/extending-the-rest-api/adding-custom-endpoints/

Ed ecco la funzione di callback

// ENDPOINT http://localhost/BEEWEB/CUSTOM-API/wp-json/api/login
// Funzione di callback a cui passo la request
 
function login(WP_REST_Request $request){
 
    // RECUPERO GLI INPUT PASSATI
 
    $arr_request = json_decode( $request->get_body() );
 
    // FACCIO IL DECODE E VERIFICO CHE ENTRAMBI NON SIANO VUOTI
 
    if( ! empty($arr_request->email) && ! empty($arr_request->password) ) {
 
    // USO LE FUNZIONI DI WP PER RECUPERARE DALLA MAIL I DATI DELL'UTENTE COME ID
 
        $user = get_user_by('email', $arr_request->email);
 
    // SE L'UTENTE NON ESISTE
 
        if(! $user ){
            // RITORNO UN ARRAY DI RISPOSTA
 
            return[
                'status' => 'error',
                'message' => 'Indirizzo email non corretto'
            ];
        }
        // VERIFICO IL LOGIN CON LA PASSWORD
 
        if( ! wp_check_password( $arr_request->password, $user->user_pass, $user->ID) ){
 
            return[
                'status' => 'error',
                'message' => 'Password errata'
            ];
        }
        // LE CREDENZALI SONO CORRETTE
 
        return[
            'status' => 'success',
            'message' => 'Le credenziali sono corrette'
        ];
    }
 
    // SE NON VENGONO PASSATI ENTRAMBI USERNAME E PASSWORD
 
    else{
        return[
            'status' => 'error',
            'message' => 'Username e password sono necessari'
        ];
    }
}

Test dell’endpoint

Noi abbiamo utilizzato per comodità l’estensione RESTClient di frefox a cui abbiamo aggiunto nell’header della richiesta 2 parametri:

Content-Type: application/json
Authorization: Basic YmVld2ViOnRMZjAgQW9ubiBGaFhDIEtnelogcFVSRSB1bjIx

Il primo ci servirà per indicare al server in che modo verranno passati i dati, in questo caso JSON, il secondo è il parametro che ci permette di accedere all’end point. La stringa alfanumerica è quella che abbiamo generato con il base64 dell’application password.

il modello dei dati passati sarà del tipo:

{
"email":"modena@beeweb.it",
"password":"123456"
}

Creo l’endpoint per la cancellazione dell’utente

Adesso creeremo un nuovo endpoint che ci permetterà di cancellare un utente. Questa volta utilizzeremo come metodo il get per poter così passare i dati tramite query string dell’url che si traduce in un parametro nell’url.

// COSTRUISCO UNA GET API REQUEST PER LA CANCELLAZIONE DI UN UTENTE
 
add_action(
    'rest_api_init',
    function(){
        register_rest_route(
            'api',
 
            '/delete_user/(?P<id>\d+)', //PARAMETRO ID
 
            array(
                'methods' => 'GET',
                'callback' => 'delete_user',
                // RENDO LA CALLBACK ACCESSIBILE SOLO PER GLI UTENTI CHE POSSONO EDITARE I POST
                'permission_callback' => function () {
                    return current_user_can( 'edit_others_posts' );
                }
            )
 
        );
 
    }
);
 
// ENDPOINT http://localhost/BEEWEB/CUSTOM-API/wp-json/api/delete_user/userid

E poi creo la callback per la cancellazione:

// COSTRUISCO LA FUNZIONE DI CALLBACK PER LA CANCELLAZIONE
 
function delete_user($data){
 
    //INCLUDO LE FUNZIONI PER GLI UTENTI
    require_once(ABSPATH.'wp-admin/includes/user.php');
 
    //CANCELLO L'UTENTE
    if( wp_delete_user($data['id']) ){
 
        return[
            'status' => 'success',
            'message' => 'Utente cancellato con successo'
        ];
 
    }
 
    //SE NON RIESCO A CANCELLARLO
    return[
        'status' => 'error',
        'message' => 'L\'operazione non è andata a buon fine'
    ];
 
}

Utilizziamo per comodità sempre l’estensione RESTClient di frefox a cui abbiamo aggiunto nell’header della richiesta 1 parametro:

Authorization: Basic YmVld2ViOnRMZjAgQW9ubiBGaFhDIEtnelogcFVSRSB1bjIx

Non ci servono altri parametri perchè l’ID dell’utente verrà passato tramite URL

Questi sono solo due esempi che hanno l’unico scopo quello di creare un ipotesi di reale utilizzo.

Molto importante se cercherete di ottenere informazioni sull’utente attualmente loggato in una callback non otterrete nessuna informazione. Per farlo dovrete includere il parametro _wpnonce alla richiesta. Per la generazione del campo potrete utilizzare wp_nonce_field oppure wp_create_nonce( ‘wp_rest’ ).

Contro di un approccio rest api

Questo tipo di applicazioni lato client nella maggior parte dei casi utilizzano JavaScript, quindi un utente che ha bloccato gli script non visualizzerà nessun risultato. Anche l’accessibilità non è sempre garantita rispetto ah una pagina HTML “standard”. Anche l’aspetto SEO è molto importante, infatti il contenuto viene renderizzato dopo il caricamento e l’esecuzione degli script, quindi il motore di ricerca potrebbe avere problemi durate i crawling delle pagine non riuscendo a leggerne il contenuto.

Conclusioni

Scegliere se utilizzare WordPress e i sui custom endpoint per la realizzazione di servizi REST deve essere sempre messa in relazione con gli obiettivi che si intende raggiungere. Sicuramente è un’interessante opportunità e secondo noi di Beeweb è importante conoscerne il funzionamento per permettere un utilizzo “moderno” del CMS più utilizzato al mondo!