Fondamenti della REST API di WordPress
La REST API di WordPress è un’interfaccia programmatica che permette a qualsiasi applicazione esterna di interagire con il sito WordPress tramite richieste HTTP standard (GET, POST, PUT, DELETE). Introdotta ufficialmente in WordPress 4.7, la REST API ha trasformato WordPress da semplice CMS a piattaforma di back-end per applicazioni moderne. I dati vengono scambiati in formato JSON, leggibile da qualsiasi linguaggio di programmazione e framework frontend.
Il funzionamento si basa su endpoint (URL) organizzati in route e namespace. Ogni risorsa di WordPress (post, pagina, utente, commento, media) ha un proprio endpoint. La struttura tipica è: /wp-json/wp/v2/posts dove wp/v2 è il namespace predefinito e posts è la risorsa. La risposta JSON include i dati richiesti più metadati utili come link correlati, informazioni di paginazione e dettagli sull’autore.
Endpoint predefiniti di WordPress
WordPress espone endpoint predefiniti per tutte le risorse principali. Endpoint dei contenuti: /wp/v2/posts (articoli), /wp/v2/pages (pagine), /wp/v2/media (file multimediali). Endpoint degli utenti: /wp/v2/users (utenti registrati), /wp/v2/users/me (utente autenticato). Endpoint delle tassonomie: /wp/v2/categories (categorie), /wp/v2/tags (tag). Altri endpoint: /wp/v2/comments (commenti), /wp/v2/settings (impostazioni sito, richiede autenticazione), /wp/v2/types (tipi di contenuto registrati), /wp/v2/statuses (stati degli articoli). Ogni endpoint accetta parametri di query per filtrare, ordinare e impaginare i risultati.
Metodi di autenticazione
La REST API supporta diversi metodi di autenticazione a seconda del caso d’uso.
Application Passwords
Introdotto in WordPress 5.6, è il metodo più semplice e sicuro per autenticare applicazioni esterne. L’utente genera una password specifica dall’area amministrativa (Utenti → Profilo → Application Passwords) e l’applicazione la usa con Basic Auth. Supporta la revoca individuale senza cambiare la password principale.
OAuth
OAuth 1.0a permette a terze parti di accedere all’API senza condividere le credenziali. Richiede un plugin (es. REST API OAuth) e un processo a tre passaggi: richiesta token, autorizzazione utente, scambio token. Ideale per applicazioni che agiscono per conto di utenti diversi.
JWT (JSON Web Token)
Il plugin JWT Authentication for WP REST API implementa l’autenticazione via token JWT. L’utente invia username e password a un endpoint di login, riceve un token JWT, e lo usa nelle richieste successive nell’header Authorization: Bearer <token>. I token hanno una scadenza configurabile e possono essere invalidati lato server. Popolare per applicazioni headless e mobile app.
Creare endpoint personalizzati
Per estendere la REST API oltre le risorse predefinite, usa register_rest_route() nel tuo plugin o in functions.php. La registrazione richiede: namespace (prefisso unico, es. mio-plugin/v1), route (es. /prodotti), e un array di opzioni che include metodi HTTP ammessi, callback di risposta, callback di autorizzazione e argomenti. Ecco uno scheletro base: add_action('rest_api_init', function() { register_rest_route('mio-plugin/v1', '/prodotti/', array( 'methods' => 'GET', 'callback' => 'mia_funzione_callback', 'permission_callback' => function() { return current_user_can('edit_posts'); } )); }); Il callback riceve un oggetto WP_REST_Request che contiene parametri, header e corpo della richiesta, e deve restituire un oggetto WP_REST_Response o un WP_Error.
Operazioni CRUD via API
La REST API supporta le quattro operazioni CRUD (Create, Read, Update, Delete). Per leggere articoli: GET /wp/v2/posts (lista) o /wp/v2/posts/123 (singolo). Per creare un articolo: POST /wp/v2/posts con body JSON contenente title, content, status, categories. Per aggiornare: PUT/PATCH /wp/v2/posts/123 con i campi da modificare. Per eliminare: DELETE /wp/v2/posts/123. Tutte le operazioni di scrittura richiedono autenticazione e permessi adeguati. La risposta include l’oggetto JSON completo della risorsa dopo l’operazione, utile per confermare il successo e aggiornare lo stato locale.
Parametri di query per la ricerca
Gli endpoint di lista accettano parametri di query per filtrare e ordinare i risultati. per_page (1-100): numero di elementi per pagina; page: numero di pagina; search: termine di ricerca; orderby: campo per ordinare (date, title, slug, modified, author, id); order: asc o desc; categories: ID categoria per filtrare; tags: ID tag per filtrare; slug: slug esatto; after e before: filtro per data in formato ISO 8601; meta_key e meta_value: filtro per metadati; status: stato del post (publish, draft, pending, private). Combinando questi parametri, puoi costruire query complesse senza scrivere una riga di PHP.
Formattazione di richieste e risposte
Le richieste GET non hanno body: i parametri vanno come query string. Le richieste POST, PUT e PATCH inviano il body in JSON con header Content-Type: application/json. La risposta include sempre: status code HTTP (200 successo, 201 creato, 400 errore validazione, 401 non autenticato, 403 non autorizzato, 404 non trovato), headers con informazioni di paginazione (X-WP-Total, X-WP-TotalPages), corpo JSON con i dati richiesti. WordPress include anche link HAL (_links) per navigare le relazioni tra risorse. Per formattare la risposta personalizzata, usa rest_ensure_response() che converte array e oggetti in WP_REST_Response validi.
WordPress headless con React e Vue
La REST API è il fondamento dell’architettura headless, dove WordPress funge solo da back-end e il frontend è costruito con framework JavaScript come React, Vue.js o Next.js. Il flusso tipico: il frontend fa una GET a /wp/v2/posts per ottenere gli articoli, usa i dati JSON per renderizzare il layout, e per le operazioni di scrittura usa POST/PUT/DELETE con autenticazione. Per un progetto headless, devi: abilitare i permalink (non in modalità Plain), configurare CORS se frontend e back-end sono su domini diversi, rimuovere le intestazioni X-WP-* non necessarie, e ottimizzare la risposta escludendo campi superflui con _fields. Vantaggi dell’architettura headless: separazione completa tra back-end e frontend, performance migliori (il frontend è HTML statico generato da un framework), sicurezza (il database non è esposto pubblicamente), e flessibilità (puoi cambiare frontend senza toccare WordPress).
Conclusioni
La REST API di WordPress è uno strumento potentissimo che apre infinite possibilità di integrazione e sviluppo. Dalla semplice lettura di articoli da un’app mobile alla complessa architettura headless con React, la REST API standardizza l’accesso ai dati di WordPress in modo elegante e prevedibile. Imparare a usare gli endpoint predefiniti, creare route personalizzate e gestire l’autenticazione ti permette di trasformare WordPress in un vero e proprio back-end API-first, adatto a qualsiasi esigenza di sviluppo moderno.