La WordPress REST API è l’interfaccia con cui applicazioni, script, plugin e servizi esterni possono leggere o modificare i dati di un sito WordPress attraverso richieste HTTP e risposte strutturate in JSON.
Puoi usarla, per esempio, per recuperare gli articoli di un sito, creare contenuti da un’applicazione esterna, sincronizzare dati con un altro software, costruire un frontend headless o sviluppare endpoint personalizzati per il tuo plugin.
Il punto di ingresso più facile da riconoscere è normalmente questo:
https://example.com/wp-json/
Da qui puoi raggiungere namespace e risorse specifiche. Per recuperare gli ultimi articoli pubblicati, per esempio:
https://example.com/wp-json/wp/v2/posts
Questa guida parte proprio da qui. Non ripeteremo tutta la teoria sulle API: se vuoi capire prima cosa sono API, endpoint, richieste e risposte, trovi il modello generale nella nostra guida su cosa sono e come funzionano le API.
Qui ci concentriamo invece su come funziona realmente la REST API di WordPress, quali endpoint espone, come interrogare i dati, quando serve autenticarsi, come creare o modificare contenuti, come registrare una route personalizzata e cosa controllare quando qualcosa non funziona.
Cos’è la WordPress REST API e quando serve davvero
WordPress espone un’interfaccia REST attraverso la quale un client può interagire con le risorse del CMS senza dover utilizzare direttamente il pannello di amministrazione o accedere al database.
La documentazione ufficiale della WordPress REST API la descrive come un’interfaccia attraverso cui le applicazioni possono inviare e ricevere dati sotto forma di oggetti JSON.
Questo significa che WordPress può fare da backend mentre un altro componente si occupa dell’interfaccia o dell’elaborazione.
Un client potrebbe essere:
- un’applicazione JavaScript;
- un’app mobile;
- uno script Python;
- un plugin WordPress;
- un gestionale;
- un CRM;
- un sistema di automazione;
- un frontend separato;
- un altro servizio web.
La tecnologia utilizzata dal client non deve necessariamente essere PHP. Ciò che conta è che sappia effettuare richieste HTTP e interpretare la risposta ricevuta.
Cosa espone WordPress tramite REST API
Il Core dispone di endpoint per numerose risorse, tra cui:
- articoli;
- pagine;
- categorie;
- tag;
- media;
- commenti;
- utenti;
- tassonomie;
- tipi di contenuto;
- template;
- menu e navigazione;
- impostazioni e altre risorse supportate dal Core.
Plugin e temi possono aggiungere ulteriori namespace ed endpoint.
Un plugin può quindi avere una propria API senza modificare gli endpoint del Core, purché registri correttamente le sue route.
REST API e API in generale non sono sinonimi
Una API è un concetto più ampio. REST identifica invece uno stile architetturale utilizzato per progettare determinate interfacce web.
Perciò:
API
└── Web API
└── REST API
è una semplificazione più utile di:
API = REST
WordPress possiede molte API interne che non sono la REST API.
Se vuoi approfondire questa distinzione, l’owner corretto è la guida generale alle API. In questa pagina ci interessa invece il comportamento concreto dell’interfaccia REST esposta dal CMS.
Un altro elemento da non confondere è JSON: JSON è il formato utilizzato per rappresentare i dati delle risposte, non è l’API e non è un linguaggio di programmazione.
Come funziona: /wp-json/, namespace, route ed endpoint
Il modello mentale più utile è:
client ↓ URL REST ↓ namespace ↓ route + metodo HTTP ↓ autenticazione/autorizzazione quando richiesta ↓ WordPress ↓ risposta HTTP + JSON
Prendiamo una chiamata concreta:
GET https://example.com/wp-json/wp/v2/posts
Qui ogni elemento ha una funzione precisa.
Il punto di ingresso /wp-json/
Con i permalink normalmente utilizzati su WordPress, la root della REST API è:
/wp-json/
Aprendo nel browser:
https://example.com/wp-json/
dovresti ricevere un documento JSON contenente informazioni sul sito e sulle route disponibili.
La root è quindi utile anche per la discovery, cioè per capire quali namespace ed endpoint sono esposti dall’installazione.
Nei siti che non utilizzano pretty permalink, WordPress può invece esporre la REST API attraverso il parametro:
?rest_route=/
La documentazione ufficiale sulla discovery della REST API descrive entrambe le modalità.
Il namespace /wp/v2/
Subito dopo /wp-json/ trovi spesso:
wp/v2
È il namespace degli endpoint principali del Core.
Per esempio:
/wp-json/wp/v2/posts /wp-json/wp/v2/pages /wp-json/wp/v2/categories /wp-json/wp/v2/tags /wp-json/wp/v2/media /wp-json/wp/v2/users
Un plugin dovrebbe usare un namespace proprio, normalmente accompagnato da una versione:
mio-plugin/v1
La versione nel namespace evita di dover modificare in modo incompatibile un contratto già utilizzato da client esterni.
Route ed endpoint non sono la stessa cosa
Questa distinzione viene spesso saltata, ma aiuta molto quando devi sviluppare o fare debugging.
Una route è l’URI che può essere associato a uno o più metodi HTTP.
Un endpoint è l’associazione tra una route e uno specifico metodo HTTP, insieme alla funzione che gestisce quella richiesta.
Prendiamo:
/wp/v2/posts
La route può rispondere a operazioni differenti.
Per esempio:
GET /wp/v2/posts POST /wp/v2/posts
L’URI è collegato alla stessa famiglia di risorse, ma i due endpoint svolgono lavori diversi.
La documentazione WordPress su route ed endpoint usa proprio questa distinzione.
GET, POST e DELETE: i metodi che incontrerai più spesso
I metodi sono HTTP, non HTML.
Nella REST API di WordPress incontrerai soprattutto:
| Metodo | Funzione tipica | Esempio |
|---|---|---|
GET | leggere una risorsa o una collezione | recuperare gli articoli |
POST | creare una risorsa | creare un articolo |
POST su una risorsa esistente | aggiornare una risorsa | modificare titolo o stato |
DELETE | eliminare una risorsa | cestinare o cancellare un articolo |
Per l’endpoint dei post, la reference ufficiale definisce infatti:
POST /wp/v2/posts
per la creazione e:
POST /wp/v2/posts/<id>
per l’aggiornamento.
Questo dettaglio conta perché applicare meccanicamente uno schema CRUD teorico a una API concreta può produrre esempi sbagliati. Quando lavori con WordPress, la reference dello specifico endpoint prevale sulla regola generica che ricordi su REST.
La risposta contiene JSON, ma anche uno status HTTP
Una richiesta non restituisce soltanto dati.
Il client deve osservare almeno:
status HTTP headers body JSON
Una risposta riuscita potrebbe contenere il documento richiesto; un errore può invece restituire un oggetto JSON con codice, messaggio e informazioni aggiuntive.
Per questo una buona integrazione non dovrebbe fare soltanto:
invia richiesta → prova a leggere il JSON
ma:
invia richiesta → controlla lo status → gestisci eventuale errore → interpreta il body
Come verificare se la REST API di WordPress funziona
Non serve installare subito Postman o scrivere un’applicazione.
Il primo test è molto più semplice.
Test dal browser
Apri:
https://tuodominio.it/wp-json/
Se la REST API è raggiungibile, dovresti ricevere una risposta JSON.
Poi prova:
https://tuodominio.it/wp-json/wp/v2/posts
Se il sito ha articoli pubblici e l’endpoint non è stato limitato, otterrai una collezione di post.
Puoi anche richiedere una singola risorsa conoscendone l’ID:
https://tuodominio.it/wp-json/wp/v2/posts/123
Sostituisci 123 con un ID realmente esistente.
Test con cURL
Da terminale:
curl https://example.com/wp-json/
oppure:
curl https://example.com/wp-json/wp/v2/posts
Se vuoi vedere anche gli header HTTP:
curl -i https://example.com/wp-json/wp/v2/posts
Questo diventa particolarmente utile quando devi controllare status code, paginazione, caching o risposta del server.
Cosa succede senza permalink “belli”
Se /wp-json/ restituisce 404 non significa automaticamente che la REST API sia disattivata.
Su configurazioni che utilizzano la struttura permalink predefinita puoi incontrare:
https://example.com/?rest_route=/
e, per esempio:
https://example.com/?rest_route=/wp/v2/posts
Prima di modificare plugin, .htaccess o configurazioni server, controlla quindi anche la struttura dei permalink WordPress.
Gli endpoint principali della WordPress REST API
La root dell’API può mostrarti ciò che è effettivamente registrato sul sito, ma alcuni endpoint del Core ricorrono molto spesso.
| Risorsa | Endpoint base |
|---|---|
| Articoli | /wp/v2/posts |
| Pagine | /wp/v2/pages |
| Media | /wp/v2/media |
| Categorie | /wp/v2/categories |
| Tag | /wp/v2/tags |
| Commenti | /wp/v2/comments |
| Utenti | /wp/v2/users |
| Tipi di contenuto | /wp/v2/types |
| Tassonomie | /wp/v2/taxonomies |
| Ricerca | /wp/v2/search |
L’URL completo aggiunge la root REST:
https://example.com/wp-json/wp/v2/posts
Post e pagine
Per recuperare gli articoli:
GET /wp-json/wp/v2/posts
Per le pagine:
GET /wp-json/wp/v2/pages
Sono endpoint distinti. Una pagina non si crea aggiungendo /pages dopo /posts.
Media, categorie e tag
Gli allegati utilizzano:
/wp-json/wp/v2/media
Le categorie:
/wp-json/wp/v2/categories
e i tag:
/wp-json/wp/v2/tags
Ogni risorsa possiede il proprio schema, i propri argomenti e i propri permessi. Prima di costruire un’integrazione conviene quindi controllare la reference ufficiale degli endpoint WordPress invece di dedurre automaticamente i parametri da un endpoint simile.
Utenti e dati protetti
L’endpoint utenti è:
/wp-json/wp/v2/users
ma ciò che puoi recuperare dipende dal contesto, dai permessi e dalla richiesta.
Questo introduce una distinzione fondamentale:
endpoint raggiungibile ≠ tutti i dati accessibili a chiunque.
La REST API applica le regole di autenticazione e autorizzazione previste da WordPress.
Come scoprire gli endpoint disponibili su un sito
Non devi affidarti esclusivamente a un elenco scritto in una guida.
Interroga:
https://example.com/wp-json/
e osserva in particolare:
namespaces routes
Plugin come WooCommerce o componenti personalizzati possono aggiungere namespace che non appartengono a wp/v2.
Questa è la differenza tra conoscere la REST API “in teoria” e sapere cosa espone quella specifica installazione WordPress.
Leggere e filtrare dati: esempi REST API WordPress
Una richiesta che recupera l’intera rappresentazione di tutti i dati disponibili è raramente il punto di arrivo di un’integrazione.
La REST API permette di filtrare, cercare, paginare e ridurre le risposte.
Recuperare gli ultimi post
La richiesta base è:
https://example.com/wp-json/wp/v2/posts
Per limitarla a cinque elementi:
https://example.com/wp-json/wp/v2/posts?per_page=5
Cercare contenuti con search
Per cercare articoli che corrispondono a una stringa:
https://example.com/wp-json/wp/v2/posts?search=wordpress
Puoi combinare più parametri:
https://example.com/wp-json/wp/v2/posts?search=wordpress&per_page=5
La sintassi corretta utilizza quindi:
?search=valore
non forme come:
?=search[valore]
La reference dei post nella REST API elenca search tra gli argomenti della collezione.
Paginazione con page e per_page
Le collezioni vengono paginate.
Per richiedere la seconda pagina:
/wp-json/wp/v2/posts?page=2
Per ottenere 20 elementi:
/wp-json/wp/v2/posts?per_page=20
e per combinare le due cose:
/wp-json/wp/v2/posts?page=2&per_page=20
per_page accetta fino a 100 elementi per richiesta.
Quando devi attraversare una collezione completa, osserva anche gli header:
X-WP-Total X-WP-TotalPages
Il primo indica il numero complessivo di elementi disponibili, il secondo quante pagine di risultati esistono con la paginazione corrente.
La documentazione WordPress sulla paginazione approfondisce anche ordinamento e altri parametri delle collezioni.
Ridurre la risposta con _fields
Immagina di dover mostrare un elenco di titoli con relativo URL.
Scaricare content, metadata, riferimenti e tutte le altre proprietà del post non ti serve.
Puoi chiedere:
/wp-json/wp/v2/posts?_fields=id,title,link
Oppure:
/wp-json/wp/v2/posts?per_page=5&_fields=id,title,link
_fields non riduce soltanto il JSON ricevuto. WordPress può anche evitare parte del lavoro necessario a generare campi che non hai richiesto.
È quindi una delle ottimizzazioni più semplici da applicare a un client che usa frequentemente la REST API.
Includere risorse correlate con _embed
Un post possiede relazioni con altre risorse: autore, termini, media e così via.
Con:
/wp-json/wp/v2/posts?_embed
puoi chiedere a WordPress di includere nella risposta anche risorse collegate che supportano l’embedding.
Questo può evitare ulteriori round trip del client.
_fields e _embed rispondono però a esigenze opposte:
_fieldsriduce ciò che ricevi;_embedaggiunge determinate risorse correlate.
Usali quindi in base ai dati realmente necessari al frontend o all’integrazione, non per abitudine.
La documentazione sui parametri globali descrive entrambe le opzioni.
Autenticazione: quando serve e come usare le Application Passwords
Una delle maggiori fonti di confusione sulla WordPress REST API è l’autenticazione.
La prima cosa da capire è che non tutte le richieste richiedono credenziali.
Se una risorsa è pubblicamente disponibile, una normale GET può essere sufficiente:
curl https://example.com/wp-json/wp/v2/posts
Diverso è il caso in cui vuoi:
- leggere contenuti privati;
- accedere a determinati contesti;
- creare contenuti;
- modificare contenuti;
- eliminare risorse;
- eseguire operazioni protette.
Qui entra in gioco l’identità dell’utente e, subito dopo, ciò che quell’utente è autorizzato a fare.
Autenticazione e autorizzazione sono due controlli diversi
Autenticazione risponde alla domanda:
chi sta effettuando questa richiesta?
Autorizzazione risponde invece a:
quell’utente può eseguire questa operazione?
Possedere credenziali valide non rende automaticamente amministratore un client REST.
WordPress continua a verificare ruoli, capability e permission callback applicabili.
Questa separazione diventa ancora più importante quando la REST API viene usata da automazioni o sistemi esterni.
Cookie authentication e X-WP-Nonce
Quando la richiesta avviene nel contesto di WordPress e l’utente è già autenticato tramite login, WordPress utilizza i cookie insieme a un REST nonce per proteggere le richieste da CSRF.
Il nonce può essere inviato nell’header:
X-WP-Nonce
Questo modello è particolarmente adatto a plugin, temi e interfacce che operano all’interno della normale sessione WordPress.
Application Passwords per applicazioni esterne
Per un client remoto, WordPress Core include le Application Passwords.
Non sono la password con cui l’utente accede normalmente a /wp-admin/.
Sono credenziali separate che puoi generare per una specifica applicazione e successivamente revocare senza cambiare la password principale dell’account.
Con HTTPS possono essere utilizzate tramite HTTP Basic Authentication.
Un esempio:
curl --user "USERNAME:APPLICATION_PASSWORD" \ https://example.com/wp-json/wp/v2/users?context=edit
La documentazione ufficiale sull’autenticazione REST indica le Application Passwords come metodo integrato per richieste remote.
Usale soltanto su HTTPS.
In un progetto reale conviene inoltre:
- usare un account con i privilegi realmente necessari;
- creare credenziali distinte per integrazioni differenti;
- revocare quelle non più usate;
- non salvare password nel repository;
- non inserirle nel JavaScript pubblico del frontend;
- gestirle attraverso secret o variabili d’ambiente quando l’architettura lo permette.
Quando OAuth o JWT hanno senso
WordPress può supportare altri sistemi di autenticazione tramite plugin o implementazioni dedicate.
OAuth o JWT possono essere corretti quando l’architettura e il modello di identità lo richiedono.
Non vanno però installati automaticamente perché “una REST API necessita di JWT”.
Per un’applicazione server-to-server semplice, le Application Passwords possono essere sufficienti. Per flussi multiutente, delega, frontend pubblici o infrastrutture più complesse, i requisiti possono essere differenti.
La scelta deve partire dal threat model e dal flusso di autenticazione, non dalla popolarità del plugin.
Creare, modificare e cancellare contenuti tramite REST API
A questo punto possiamo passare dalle letture pubbliche alle operazioni che modificano WordPress.
Gli esempi seguenti utilizzano curl, HTTPS e una Application Password.
Creare un articolo con POST
curl --user "USERNAME:APPLICATION_PASSWORD" \
-X POST https://example.com/wp-json/wp/v2/posts \
-H "Content-Type: application/json" \
-d '{
"title": "Titolo di prova",
"content": "Contenuto di prova",
"status": "draft"
}'
Il client invia un oggetto JSON contenente i campi che vuole impostare.
Usare inizialmente:
"status": "draft"
è una scelta prudente durante lo sviluppo, perché evita di pubblicare accidentalmente contenuti di test.
Aggiornare un contenuto esistente
Per modificare l’articolo con ID 123:
curl --user "USERNAME:APPLICATION_PASSWORD" \
-X POST https://example.com/wp-json/wp/v2/posts/123 \
-H "Content-Type: application/json" \
-d '{
"title": "Nuovo titolo"
}'
Puoi aggiornare soltanto i campi necessari.
Per esempio:
{
"status": "publish"
}
cambia lo stato se l’utente autenticato dispone dei permessi richiesti.
Eliminare un articolo
La richiesta:
curl --user "USERNAME:APPLICATION_PASSWORD" \ -X DELETE https://example.com/wp-json/wp/v2/posts/123
utilizza l’endpoint di eliminazione.
Per bypassare il Cestino quando la risorsa supporta questa modalità:
curl --user "USERNAME:APPLICATION_PASSWORD" \ -X DELETE "https://example.com/wp-json/wp/v2/posts/123?force=true"
force=true va trattato con molta cautela: può trasformare una cancellazione recuperabile in una rimozione definitiva.
Autenticazione non significa automaticamente autorizzazione
Supponiamo che le credenziali siano valide ma l’utente non possa pubblicare articoli.
La richiesta rimane autenticata, ma WordPress deve comunque impedirgli di effettuare un’operazione per cui non possiede la capability necessaria.
Per questo un’integrazione ben progettata non dovrebbe usare indiscriminatamente un account amministratore solo per evitare problemi di permessi.
Concedi al client il minimo privilegio necessario al suo lavoro.
Come creare un endpoint REST personalizzato in WordPress
La REST API non è limitata agli endpoint del Core.
Plugin e codice custom possono registrare nuove route con:
register_rest_route()
La registrazione va effettuata nel ciclo REST appropriato.
Un esempio minimale:
add_action( 'rest_api_init', function () {
register_rest_route(
'creativemotions/v1',
'/status',
array(
'methods' => 'GET',
'callback' => 'creativemotions_get_status',
'permission_callback' => '__return_true',
)
);
} );
function creativemotions_get_status() {
return array(
'status' => 'ok',
);
}
L’endpoint diventa:
https://example.com/wp-json/creativemotions/v1/status
Namespace e versioning
In:
creativemotions/v1
creativemotions identifica il namespace e v1 la versione del contratto.
Questa convenzione riduce il rischio di collisioni con altri plugin e ti permette di introdurre in futuro una v2 senza rompere immediatamente i client che utilizzano la prima versione.
Evita namespace generici come:
api/v1
se stai sviluppando un plugin destinato a convivere con codice di terze parti.
permission_callback non è facoltativa nella progettazione
Una route deve dichiarare esplicitamente come vengono gestiti i permessi.
Per una route realmente pubblica:
'permission_callback' => '__return_true'
può essere appropriato.
Per una route protetta potresti invece controllare una capability:
'permission_callback' => function () {
return current_user_can( 'manage_options' );
}
Non usare __return_true soltanto per far scomparire un warning.
La domanda da farti è:
chi dovrebbe poter eseguire questa operazione?
La reference ufficiale di register_rest_route() e la guida agli endpoint REST personalizzati entrano nel dettaglio del modello.
Validazione e sanitizzazione degli input
Un endpoint che accetta dati dal client non dovrebbe assumere che siano corretti solo perché il JSON è sintatticamente valido.
Puoi definire per gli argomenti:
- tipo;
- obbligatorietà;
- valore di default;
- validazione;
- sanitizzazione.
Un input valido a livello JSON può comunque essere inaccettabile per la tua applicazione.
Per esempio:
{
"post_id": -500
}
è JSON valido, ma potrebbe non avere alcun senso per una funzione che richiede un ID reale e positivo.
La validazione deve quindi precedere la business logic ogni volta che il dato può influire sull’operazione.
Sicurezza della WordPress REST API: cosa proteggere davvero
Il fatto che:
https://example.com/wp-json/
sia raggiungibile non dimostra automaticamente che il sito abbia una vulnerabilità.
La REST API è una parte funzionale dell’ecosistema WordPress e viene utilizzata anche da componenti del CMS, incluso l’editor a blocchi.
Il problema di sicurezza non si risolve quindi con l’equazione:
endpoint pubblico = sito vulnerabile
Bisogna valutare quali risorse sono esposte, quali operazioni sono consentite, quali dati ritornano e quali permessi vengono verificati.
Dati pubblici non significa accesso amministrativo
Gli articoli pubblicati sono già accessibili visitando il sito.
La possibilità di leggerne una rappresentazione JSON non significa poterli modificare.
Una richiesta di scrittura deve superare i controlli previsti dall’endpoint.
Allo stesso modo, un endpoint custom pubblico che restituisce informazioni sensibili rimane una cattiva progettazione anche se tecnicamente funziona.
La distinzione utile è:
pubblico intenzionale ≠ dato sensibile esposto per errore
HTTPS, credenziali e privilegi minimi
Per le integrazioni autenticate:
- usa HTTPS;
- non esporre credenziali nel frontend;
- evita credenziali condivise fra più applicazioni quando puoi separarle;
- revoca quelle inutilizzate;
- assegna privilegi minimi;
- valida e sanitizza gli input;
- registra e monitora gli errori significativi.
Una Application Password non protegge da una cattiva gestione delle credenziali. Offre semplicemente un meccanismo migliore per separare l’accesso dell’applicazione dalla password principale dell’utente.
Perché disattivare tutta la REST API è spesso una soluzione troppo drastica
Bloccare indiscriminatamente /wp-json/ può interferire con plugin, editor, applicazioni e integrazioni che la utilizzano legittimamente.
Se il problema è un endpoint specifico, una quantità anomala di richieste o un dato che non dovrebbe essere pubblico, intervieni sul problema reale.
Potresti dover:
- correggere i permessi dell’endpoint;
- limitare una determinata route;
- intervenire sul WAF;
- applicare rate limiting;
- correggere una configurazione;
- aggiornare il plugin responsabile;
- rimuovere un endpoint custom non più necessario.
Ridurre la superficie inutilizzata è sensato. Rompere una API funzionante per nascondere dati già pubblici spesso non lo è.
Se il sito presenta problemi tecnici più ampi e non vuoi intervenire direttamente sul codice o sul server, puoi valutare un servizio di assistenza WordPress dopo aver isolato la causa.
REST API, HTTP API, XML-RPC, WooCommerce API, Abilities API e MCP
WordPress possiede diversi livelli di interoperabilità. Metterli tutti sotto l’etichetta “API WordPress” crea più confusione che vantaggi.
| Tecnologia | A cosa serve principalmente | Sostituisce la REST API? |
|---|---|---|
| WordPress REST API | espone risorse e operazioni WordPress tramite HTTP/JSON | no, è l’oggetto di questa guida |
| WordPress HTTP API | permette al codice PHP di WordPress di effettuare richieste HTTP verso altri servizi | no |
| XML-RPC | interfaccia storica per operazioni remote basata su XML/RPC | no |
| WooCommerce REST API | espone risorse ecommerce come prodotti e ordini | no, è un’API verticale |
| Abilities API | registra e descrive capacità eseguibili in modo standardizzato | no |
| MCP | permette a client e agenti compatibili di scoprire e usare strumenti attraverso un protocollo condiviso | no |
REST API e XML-RPC
XML-RPC in WordPress è un’interfaccia storica separata.
La REST API usa HTTP e JSON secondo un modello diverso. XML-RPC continua però a esistere e può essere necessario per determinate integrazioni.
Per questo non va disattivato o sostituito partendo soltanto dall’idea che “REST è più nuovo”.
Devi verificare chi utilizza l’interfaccia sul sito reale.
WordPress REST API e WooCommerce REST API
WooCommerce aggiunge endpoint dedicati alle risorse ecommerce.
Se devi lavorare con:
- prodotti;
- ordini;
- clienti;
- coupon;
- altre risorse WooCommerce;
l’owner specifico è la guida sulla WooCommerce REST API.
La REST API di WordPress resta il contesto architetturale generale, ma non ha senso duplicare qui tutta la reference WooCommerce.
REST API e Abilities API
La WordPress Abilities API affronta un problema differente: descrivere e registrare capacità che altri componenti software possono scoprire e utilizzare.
Una Ability può essere esposta attraverso REST quando previsto, ma:
Ability ≠ endpoint REST
L’Ability descrive una capacità e il relativo contratto; REST può essere uno dei modi con cui quella capacità diventa raggiungibile da un client.
REST API e MCP
Anche WordPress MCP non sostituisce la REST API.
MCP risolve soprattutto il problema dell’interoperabilità tra client, agenti e strumenti.
Un’architettura può quindi avere:
AI Agent ↓ MCP ↓ strumento / Ability ↓ logica WordPress ↓ REST API quando necessaria
I livelli possono cooperare senza essere sinonimi.
WordPress REST API e WordPress headless
Un utilizzo molto conosciuto della REST API consiste nel separare la gestione dei contenuti dalla loro presentazione.
WordPress rimane il backend editoriale, mentre il frontend può essere realizzato con una tecnologia diversa e recuperare i dati attraverso API.
Per esempio:
WordPress ↓ REST API ↓ frontend separato
Questo è uno dei possibili modelli di WordPress headless.
Non significa però che:
REST API = headless
Puoi utilizzare la REST API in un sito WordPress tradizionale e puoi costruire architetture headless utilizzando anche altri livelli di accesso ai dati.
Quando REST è un buon data layer
REST può essere adatta quando:
- i client lavorano naturalmente con richieste HTTP;
- le risorse richieste corrispondono bene agli endpoint disponibili;
- vuoi utilizzare le API già fornite dal Core;
- l’integrazione non necessita di query arbitrarie molto complesse;
- vuoi mantenere una dipendenza relativamente bassa da componenti aggiuntivi.
REST vs GraphQL non ha un vincitore universale
GraphQL può essere utile quando il client deve comporre query molto specifiche e controllare granularmente la struttura dei dati ricevuti.
REST può essere più lineare quando risorse e operazioni sono già ben rappresentate dagli endpoint disponibili.
La scelta architetturale dipende dal frontend, dalla cache, dall’autenticazione, dalla complessità delle query, dalla governance dell’API e dalle competenze del team.
Per non duplicare un tema molto più ampio, trovi il confronto nel nostro approfondimento su WordPress headless.
Errori comuni della REST API e come diagnosticarli
Quando una richiesta fallisce, evitare modifiche casuali fa risparmiare molto tempo.
Il metodo più utile è:
URL → metodo → status HTTP → body dell'errore → autenticazione → autorizzazione → permalink/rewrite → plugin/WAF/cache → log server/PHP
rest_no_route e 404
Un errore simile a:
rest_no_route
indica generalmente che WordPress non riesce a trovare una route compatibile con URL e metodo utilizzati.
Controlla:
- root
/wp-json/; - namespace;
- versione;
- route;
- metodo HTTP;
- eventuali slash o parametri errati;
- registrazione dell’endpoint custom.
Se la root stessa restituisce 404, verifica anche permalink e rewrite.
401: prima controlla l’autenticazione
Un 401 indica normalmente che la richiesta non dispone di credenziali valide per accedere alla risorsa richiesta.
Controlla:
- username;
- Application Password;
- header
Authorization; - HTTPS;
- proxy/CDN;
- server che potrebbe rimuovere l’header.
Non partire modificando i ruoli dell’utente se WordPress non riesce nemmeno a identificarlo.
403: autenticato non significa autorizzato
Un 403 orienta invece maggiormente verso il controllo dei permessi.
La richiesta può essere riconosciuta ma l’utente non possiede la capability necessaria, oppure una permission callback, un plugin di sicurezza o un WAF impedisce l’operazione.
È proprio qui che la distinzione tra autenticazione e autorizzazione diventa operativa.
Quando i query parameter sembrano ignorati
Se:
?page=2
oppure:
?_embed
non producono alcun effetto, il problema può trovarsi nella configurazione del web server.
La documentazione ufficiale delle FAQ della REST API segnala, per esempio, configurazioni Nginx in cui i query argument non vengono inoltrati correttamente a WordPress.
Prima di accusare l’endpoint, verifica quindi la richiesta realmente ricevuta dal CMS.
WAF, cache e plugin di sicurezza
Una REST API può funzionare correttamente nel Core e fallire comunque lungo il percorso.
La richiesta può attraversare:
client → CDN → WAF → web server → WordPress → plugin → endpoint
Un 403, un timeout o una risposta modificata possono quindi essere prodotti prima che la callback REST venga eseguita.
Per fare debugging:
- riproduci la richiesta con
curl; - registra status, header e body;
- confronta richiesta autenticata e non autenticata;
- controlla log server e PHP;
- verifica WAF/CDN;
- disattiva selettivamente il componente sospetto in staging;
- evita di abbassare globalmente la sicurezza per far funzionare un singolo endpoint.
Domande frequenti sulla WordPress REST API
Qual è l’URL della WordPress REST API?
Con permalink standard moderni, la root è normalmente:
https://tuodominio.it/wp-json/
Gli endpoint del Core si trovano generalmente sotto namespace come:
/wp-json/wp/v2/
Con permalink predefiniti puoi incontrare anche ?rest_route=/.
Che cos’è wp-json?
wp-json è normalmente il prefisso della root REST di WordPress quando vengono utilizzati pretty permalink.
Non indica un file wp-json presente nella root del server.
È un percorso gestito dal sistema di routing di WordPress.
WordPress REST API è attiva di default?
L’infrastruttura REST e gli endpoint del Core fanno parte di WordPress.
Plugin, configurazioni server o codice custom possono però limitare route, dati o accesso. Il test corretto consiste quindi nel verificare il sito reale attraverso /wp-json/ e gli endpoint necessari.
La REST API è sicura?
Può esserlo, ma la sicurezza dipende dall’implementazione.
Devi considerare:
- dati esposti;
- autenticazione;
- autorizzazione;
- capability;
- permission callback;
- gestione delle credenziali;
- HTTPS;
- validazione degli input;
- WAF e server;
- endpoint aggiunti dai plugin.
La semplice presenza di /wp-json/ non prova una vulnerabilità.
È necessario autenticarsi per leggere gli articoli?
Normalmente gli articoli pubblici possono essere letti senza autenticazione.
Risorse private, determinati contesti e operazioni di scrittura richiedono invece autenticazione e permessi appropriati.
Come posso creare una REST API personalizzata in WordPress?
Puoi registrare route ed endpoint attraverso register_rest_route() durante rest_api_init.
Definisci almeno:
- namespace;
- route;
- metodo;
- callback;
- permission callback;
e, quando accetti input, anche regole coerenti di validazione e sanitizzazione.
La WordPress REST API serve solo per JavaScript?
No.
Qualunque client capace di effettuare richieste HTTP e interpretare JSON può utilizzarla.
Puoi lavorare da PHP, JavaScript, Python, Java, Go, strumenti da riga di comando o altri ambienti.
REST API e WooCommerce REST API sono la stessa cosa?
No.
WooCommerce espone endpoint propri, orientati al dominio ecommerce. Il modello REST è collegato, ma namespace, risorse, autenticazione e reference devono essere verificati rispetto a WooCommerce.
Devo disabilitare /wp-json/ per sicurezza?
Non come intervento automatico.
Prima identifica quale rischio vuoi mitigare. Limitare un endpoint custom mal progettato, proteggere una route sensibile o bloccare traffico abusivo è diverso dal disattivare indiscriminatamente l’interfaccia REST.
Conclusione
La WordPress REST API diventa molto meno astratta quando smetti di considerarla semplicemente come “un modo per collegare WordPress ad altre applicazioni” e inizi a leggerla come una sequenza precisa:
/wp-json/ → namespace → route → metodo → parametri → autenticazione → autorizzazione → risposta JSON
Per iniziare, non serve sviluppare subito un’applicazione completa. Apri /wp-json/, interroga /wp/v2/posts, prova search, per_page e _fields, poi passa a una richiesta autenticata in un ambiente di test.
Quando inizi a modificare dati, la priorità cambia: permessi, credenziali, validazione e gestione degli errori diventano importanti quanto l’endpoint stesso.
E se devi estendere WordPress, crea route specifiche con namespace chiari e permission callback coerenti invece di trasformare un singolo endpoint in un accesso generico a tutta la logica dell’applicazione.
È questa la differenza tra fare una chiamata REST che “funziona” e progettare un’integrazione WordPress che resta comprensibile, controllabile e manutenibile.