WordPress REST API: Guida per Sviluppatori e Integrazioni
La WordPress REST API ha trasformato WordPress da semplice CMS a piattaforma applicativa completa. Introdotta come feature nativa a partire da WordPress 4.7, la REST API espone i contenuti e le funzionalità di WordPress attraverso endpoint HTTP standard, permettendo a qualsiasi applicazione — mobile, desktop, web o IoT — di interagire con un sito WordPress in modo programmatico. Nel 2026, la REST API è il cuore delle architetture headless, delle single-page application (SPA) e delle integrazioni tra WordPress e sistemi esterni.
Questa guida è pensata per sviluppatori che vogliono comprendere e sfruttare al massimo le potenzialità della REST API di WordPress. Copriremo i concetti fondamentali, gli endpoint disponibili, l’autenticazione, la creazione di endpoint personalizzati e le best practice per integrazioni robuste e performanti.
Cos’è una REST API
REST (Representational State Transfer) è un’architettura software per la comunicazione tra sistemi tramite il protocollo HTTP. Una REST API espone risorse (nel caso di WordPress: articoli, pagine, utenti, commenti, media) tramite URL (endpoint) e utilizza i metodi HTTP standard per le operazioni CRUD:
GET: recupera dati (leggere un articolo, elencare le pagine).
POST: crea nuovi dati (pubblicare un articolo, caricare un’immagine).
PUT/PATCH: aggiorna dati esistenti (modificare un articolo, aggiornare un utente).
DELETE: elimina dati (cancellare un commento, rimuovere un media).
I dati vengono scambiati in formato JSON (JavaScript Object Notation), un formato leggero e universalmente supportato da ogni linguaggio di programmazione. Questo rende la REST API di WordPress accessibile da qualsiasi tecnologia: JavaScript, Python, PHP, Swift, Kotlin, Ruby, Go e praticamente qualsiasi altro linguaggio.
Struttura degli endpoint
Tutti gli endpoint della REST API di WordPress risiedono sotto il percorso base /wp-json/wp/v2/. Ecco gli endpoint principali:
/wp-json/wp/v2/posts: articoli del blog. Supporta filtri per categoria, tag, autore, data, ricerca e stato.
/wp-json/wp/v2/pages: pagine statiche.
/wp-json/wp/v2/categories: categorie degli articoli.
/wp-json/wp/v2/tags: tag degli articoli.
/wp-json/wp/v2/media: file media (immagini, video, documenti).
/wp-json/wp/v2/users: utenti registrati.
/wp-json/wp/v2/comments: commenti.
/wp-json/wp/v2/search: ricerca globale nei contenuti.
/wp-json/wp/v2/settings: impostazioni del sito (richiede autenticazione).
Per accedere a una singola risorsa, aggiungi l’ID all’endpoint: /wp-json/wp/v2/posts/42 restituisce l’articolo con ID 42.
Puoi esplorare l’API del tuo sito aprendo nel browser: tuodominio.it/wp-json/wp/v2/. Vedrai l’elenco degli endpoint disponibili con la loro documentazione interattiva.
Parametri di query comuni
Gli endpoint GET supportano numerosi parametri per filtrare e personalizzare i risultati:
per_page: numero di risultati per pagina (default 10, massimo 100). Esempio: ?per_page=25
page: numero di pagina per la paginazione. Esempio: ?page=2
search: ricerca testuale nei contenuti. Esempio: ?search=wordpress
categories: filtra per ID categoria. Esempio: ?categories=5,12
tags: filtra per ID tag. Esempio: ?tags=8
author: filtra per ID autore. Esempio: ?author=1
orderby: ordina i risultati (date, title, id, slug, modified). Esempio: ?orderby=title
order: direzione dell’ordinamento (asc, desc). Esempio: ?order=asc
status: stato del contenuto (publish, draft, pending — richiede autenticazione per draft/pending). Esempio: ?status=publish
_fields: seleziona solo i campi specificati (riduce la dimensione della risposta). Esempio: ?_fields=id,title,link
_embed: include dati correlati (autore, media in evidenza, categorie) nella risposta. Esempio: ?_embed
I parametri possono essere combinati: /wp-json/wp/v2/posts?categories=5&per_page=5&orderby=date&order=desc&_fields=id,title,excerpt,link restituisce gli ultimi 5 articoli della categoria 5 con solo ID, titolo, estratto e link.
Autenticazione
Gli endpoint di sola lettura (GET) per contenuti pubblici non richiedono autenticazione. Ma per creare, modificare o eliminare contenuti, o per accedere a dati privati (bozze, impostazioni), serve un’autenticazione.
WordPress supporta diversi metodi di autenticazione per la REST API:
Cookie Authentication
Il metodo nativo per le richieste JavaScript all’interno della dashboard di WordPress. Utilizza il cookie di sessione dell’utente loggato e un nonce per la protezione CSRF. È il metodo usato dall’editor Gutenberg e dai plugin che interagiscono con la REST API dal front-end. Non adatto per applicazioni esterne.
Application Passwords
Introdotte in WordPress 5.6, le Application Passwords permettono di generare password dedicate per applicazioni esterne. Ogni utente può creare una o più application password dalla pagina del profilo (Utenti → Profilo → Application Passwords). Le richieste si autenticano tramite HTTP Basic Auth con username e application password. È il metodo più semplice per integrazioni server-to-server.
Esempio di utilizzo con curl: curl -u "username:xxxx xxxx xxxx xxxx" https://tuodominio.it/wp-json/wp/v2/posts
Le application password sono specifiche per ogni applicazione e possono essere revocate individualmente senza cambiare la password dell’utente. Richiedono HTTPS (non funzionano su HTTP non criptato).
OAuth 2.0
Per integrazioni più complesse che richiedono autorizzazione delegata (un’app di terze parti agisce per conto dell’utente), OAuth 2.0 è lo standard. Richiede un plugin aggiuntivo come WP OAuth Server o l’integrazione con un identity provider esterno. È il metodo consigliato per applicazioni pubbliche che accedono ai dati di più utenti.
JWT (JSON Web Token)
Un’alternativa popolare per applicazioni headless. Il client si autentica con username e password e riceve un token JWT che include nelle successive richieste nell’header Authorization. Plugin come JWT Authentication for WP REST API implementano questo metodo. I token JWT hanno una scadenza configurabile, aggiungendo un livello di sicurezza temporale.
Creare endpoint personalizzati
Una delle funzionalità più potenti della REST API è la possibilità di creare endpoint personalizzati. Questo è essenziale quando hai bisogno di esporre dati che non sono coperti dagli endpoint standard o quando vuoi creare un’API specifica per la tua applicazione.
Gli endpoint personalizzati si registrano usando la funzione register_rest_route() all’interno dell’hook rest_api_init. La funzione accetta il namespace dell’API (per evitare conflitti con altri plugin), il percorso dell’endpoint, i metodi HTTP supportati, la funzione callback che gestisce la richiesta e opzionalmente una funzione di controllo permessi.
Ecco i componenti di un endpoint personalizzato:
Namespace: un identificatore univoco per la tua API, tipicamente nel formato "mioplugin/v1". Serve a evitare conflitti con endpoint di altri plugin.
Route: il percorso dell’endpoint dopo il namespace. Può includere parametri dinamici tra parentesi graffe, ad esempio "/prodotti/(?P<id>d+)" per catturare un ID numerico.
Callback: la funzione PHP che elabora la richiesta e restituisce i dati. Riceve un oggetto WP_REST_Request con accesso a parametri, body, headers e file caricati.
Permission callback: la funzione che verifica se l’utente ha i permessi per accedere all’endpoint. Può controllare ruoli, capability specifiche o implementare logica personalizzata.
Args: definizione dei parametri accettati dall’endpoint con validazione e sanitizzazione. Permette di specificare tipo di dato, valori predefiniti, se il parametro è obbligatorio e funzioni di validazione personalizzate.
WordPress come Headless CMS
L’architettura headless utilizza WordPress solo come back-end per la gestione dei contenuti, mentre il front-end è costruito con framework JavaScript moderni come React, Vue.js, Next.js o Nuxt.js. La REST API è il ponte tra i due mondi.
Vantaggi dell’approccio headless: performance superiori (le pagine sono generate staticamente o lato client), totale libertà nella scelta del framework front-end, esperienza utente simile a un’app nativa (SPA), possibilità di servire gli stessi contenuti su web, mobile e altri canali e scalabilità del front-end indipendente dal back-end.
Svantaggi: complessità di sviluppo maggiore, perdita del preview WYSIWYG di WordPress, necessità di gestire separatamente SEO (SSR o SSG), impossibilità di usare plugin WordPress che agiscono sul front-end (page builder, plugin di design) e costi di sviluppo e manutenzione più elevati.
Quando usare headless: l’approccio headless è giustificato per applicazioni web complesse, progetti multi-canale (stesso contenuto su web e app), siti con esigenze di performance estreme o quando il team di sviluppo front-end preferisce lavorare con framework JavaScript moderni.
Framework popolari per WordPress headless: Next.js (React) con il plugin Faust.js, Nuxt.js (Vue.js) con il plugin WPNuxt, Gatsby (React) con il plugin gatsby-source-wordpress e Astro con integrazioni WordPress.
Esporre custom post types e custom fields
Per rendere i custom post types (CPT) accessibili tramite la REST API, devi impostare il parametro show_in_rest a true nella registrazione del CPT con register_post_type(). Puoi anche personalizzare il namespace e il controller REST con i parametri rest_base e rest_controller_class.
Per i custom fields (post meta), registrali con register_post_meta() impostando show_in_rest a true. Puoi specificare il tipo di dato, la validazione e se il campo è un singolo valore o un array. I custom fields registrati in questo modo appaiono nel campo "meta" della risposta JSON dell’endpoint del CPT.
Per campi complessi (ACF, Meta Box, Pods), i rispettivi plugin offrono integrazioni native con la REST API che espongono automaticamente i campi personalizzati negli endpoint.
Performance e caching della REST API
Le chiamate REST API possono essere costose in termini di performance, specialmente sotto carico. Ecco le best practice per ottimizzare:
Usa _fields per ridurre i dati: il parametro ?_fields=id,title,link restituisce solo i campi specificati, riducendo drasticamente la dimensione della risposta JSON e il tempo di elaborazione.
Cache lato server: implementa la cache delle risposte REST API usando header HTTP di cache (Cache-Control, ETag). Plugin come WP REST Cache memorizzano le risposte e le invalidano automaticamente quando i contenuti cambiano.
CDN per l’API: se l’API è pubblica e i dati cambiano raramente, puoi cacheare le risposte tramite CDN. Cloudflare, ad esempio, può cacheare le risposte JSON con regole di page cache specifiche per il percorso /wp-json/.
Paginazione efficiente: non richiedere più dati del necessario. Usa per_page e page per la paginazione e implementa l’infinite scroll o il caricamento on-demand nel client.
Disabilita endpoint non utilizzati: se non usi la REST API per il front-end del sito, puoi disabilitare gli endpoint pubblici per ridurre la superficie di attacco e le risorse consumate. Usa il filtro rest_endpoints per rimuovere endpoint specifici.
Sicurezza della REST API
La REST API espone dati del sito e, se mal configurata, può rappresentare un rischio per la sicurezza:
Limita l’accesso agli utenti: l’endpoint /wp-json/wp/v2/users espone per impostazione predefinita gli username di tutti gli utenti. Se non serve, disabilita questo endpoint o limita i dati esposti con il filtro rest_prepare_user.
Autenticazione obbligatoria per operazioni di scrittura: WordPress lo gestisce nativamente, ma assicurati che i tuoi endpoint personalizzati implementino sempre il permission_callback. Non lasciare mai un permission_callback vuoto o che restituisce sempre true per endpoint che modificano dati.
Validazione e sanitizzazione degli input: per ogni parametro degli endpoint personalizzati, definisci funzioni di validazione (validate_callback) e sanitizzazione (sanitize_callback). Non fidarti mai dell’input dell’utente, anche se autenticato.
Rate limiting: implementa il rate limiting per prevenire abusi e attacchi DDoS. Plugin come WP REST API Rate Limit o la configurazione a livello server (nginx limit_req, Apache mod_ratelimit) proteggono da richieste eccessive.
CORS: se la REST API è consumata da un dominio diverso, configura i header CORS (Cross-Origin Resource Sharing) per limitare l’accesso ai domini autorizzati. Il filtro rest_pre_serve_request permette di personalizzare gli header CORS.
Integrazioni pratiche con la REST API
Ecco alcuni scenari reali di integrazione che puoi implementare con la REST API:
App mobile: un’app iOS o Android che mostra gli articoli del blog, permette la lettura offline e invia notifiche push per nuovi contenuti. L’app comunica con WordPress esclusivamente tramite REST API.
Dashboard esterna: un pannello di controllo personalizzato costruito con React o Vue.js che permette ai redattori di gestire articoli, media e commenti con un’interfaccia ottimizzata per il loro workflow.
Integrazione CRM: quando un utente compila un modulo di contatto, un webhook invia i dati alla REST API di un CRM esterno (HubSpot, Salesforce) creando automaticamente un lead.
Digital signage: schermi informativi in negozi o uffici che mostrano contenuti gestiti da WordPress, aggiornati in tempo reale tramite REST API.
Aggregatore multi-sito: un portale che raccoglie e mostra contenuti da più siti WordPress tramite le rispettive REST API, creando un hub informativo centralizzato.
Chatbot: un chatbot che cerca risposte nelle FAQ e negli articoli del sito tramite l’endpoint di ricerca della REST API.
Strumenti per lo sviluppo e il debug
Alcuni strumenti essenziali per lavorare con la REST API:
Postman: il tool standard per testare API. Permette di costruire richieste HTTP con header, parametri e body personalizzati, salvare collezioni di richieste e automatizzare i test.
Insomnia: alternativa open source a Postman con un’interfaccia pulita e supporto nativo per GraphQL.
Browser DevTools: il tab Network delle DevTools del browser è utilissimo per monitorare le chiamate REST API fatte dall’editor Gutenberg e dai plugin.
WP-CLI: il comando wp rest permette di interagire con la REST API dalla linea di comando, utile per script e automazioni.
Conclusioni
La WordPress REST API nel 2026 è una tecnologia matura e potente che apre possibilità infinite per l’integrazione di WordPress con il mondo delle applicazioni moderne. Che tu stia costruendo un’app mobile, un front-end headless, un’integrazione con servizi esterni o semplicemente automatizzando workflow interni, la REST API è lo strumento giusto.
La chiave è progettare le integrazioni con attenzione alla sicurezza, alle performance e alla manutenibilità. Un’API ben progettata è un investimento che abilita innovazione e scalabilità per anni a venire.
Se hai bisogno di sviluppare integrazioni WordPress personalizzate o di costruire un’applicazione basata sulla REST API, il nostro team di sviluppatori è a disposizione per trasformare la tua idea in realtà.
Approfondisci e ricevi assistenza
Hai bisogno di assistenza professionale? Il team di G Tech Group è a tua disposizione per supporto tecnico e consulenza personalizzata.
Migliora il Tuo Sito WordPress
Scopri le nostre guide complete sugli altri plugin essenziali per WordPress: