L'API REST di WordPress fornisce endpoint predefiniti potenti per articoli, pagine, utenti e media. Ma la funzionalità reale di un plugin spesso richiede endpoint personalizzati che espongano i dati e le operazioni specifiche del tuo plugin. Gli endpoint personalizzati ti permettono di creare la superficie API esatta di cui la tua applicazione ha bisogno, seguendo il tuo modello di dati e la tua logica di business.
Questa guida copre come creare endpoint API REST personalizzati per il tuo plugin WordPress, dalla registrazione di base delle rotte alla gestione di query complesse.
Registrazione delle Route
Registra endpoint personalizzati con register_rest_route() durante l'hook rest_api_init. Ogni route ha un namespace (l'identificatore del tuo plugin con la versione), un percorso di route e un array di endpoint. Ogni endpoint specifica i metodi HTTP, una callback di permessi e una callback handler. Il namespace dovrebbe seguire il pattern 'tuo-plugin/v1'.
Le rotte possono includere variabili di percorso usando la sintassi regex tra parentesi. Una rotta come '/bookings/(?P\d+)' cattura l'ID della prenotazione dall'URL e lo passa all'handler come parametro.
Richiesta e Risposta
La callback dell'handler riceve un oggetto WP_REST_Request contenente parametri, header e dati di autenticazione. Usa $request->get_param() per accedere ai singoli parametri, $request->get_params() per tutti i parametri e $request->get_header() per gli header HTTP. Restituisci un oggetto WP_REST_Response o WP_Error dal tuo handler.
Imposta codici di stato HTTP appropriati: 200 per richieste GET riuscite, 201 per risorse create, 400 per richieste errate, 403 per accessi vietati e 404 per risorse non trovate. Usa rest_ensure_response() per normalizzare i tuoi dati di risposta nel formato standard dell'API REST.
Registrazione dello Schema
Uno schema descrive la struttura dati del tuo endpoint e viene utilizzato per documentazione, validazione e scoperta. Registra uno schema con register_rest_field() o includilo direttamente nella registrazione della rotta. Lo schema definisce le proprietà, i loro tipi, se sono obbligatorie e i valori predefiniti.
WordPress valida automaticamente i parametri della richiesta rispetto al tuo schema e restituisce messaggi di errore significativi quando la validazione fallisce. Uno schema ben definito rende la tua API più facile da usare e più affidabile.
Callback di Permessi
Ogni endpoint necessita di un callback di autorizzazione che restituisce true o false. Per gli endpoint pubblici, restituisci ‘__return_true’. Per gli endpoint solo autenticati, controlla is_user_logged_in(). Per gli endpoint specifici per ruolo, usa current_user_can().
Sii specifico sui permessi. Un utente potrebbe avere il permesso di leggere i propri dati ma non quelli degli altri. Verifica la proprietà della risorsa nella callback di permessi confrontando l'ID dell'utente corrente con l'ID del proprietario della risorsa.
Endpoint di Collezione
Gli endpoint di collezione restituiscono elenchi di risorse. Supporta la paginazione con i parametri 'per_page' e 'page'. Usa WP_Query o get_posts() con i parametri di paginazione applicati. Restituisci gli header di paginazione con $response->header('X-WP-Total', $total) e $response->header('X-WP-TotalPages', $pages).
Supporta il filtraggio con parametri di query personalizzati come 'search', 'after', 'before' e filtri specifici del plugin. Documenta chiaramente i parametri supportati. Se il tuo endpoint restituisce molte risorse, assicurati che sia adeguatamente indicizzato e performante.
Il punto fondamentale
Gli endpoint REST API personalizzati trasformano il tuo plugin da uno strumento specifico di WordPress in una piattaforma che può integrarsi con qualsiasi applicazione. Registra le rotte con un namespace corretto, gestisci richieste e risposte con le classi WordPress corrette, definisci schemi per documentazione e validazione, e proteggi gli endpoint con callback di autorizzazione adeguati. Un'API ben progettata estende la portata del tuo plugin ben oltre l'amministrazione di WordPress.
