Guida alla REST API di WordPress

Che cos'è la REST API di WordPress

La REST API dell'ecosistema WordPress è un'interfaccia che permette alle applicazioni esterne di comunicare con un sito WordPress tramite richieste HTTP. Invece di accedere ai contenuti attraverso il frontend o il pannello di amministrazione di WordPress, la REST API ti consente di leggere, creare, aggiornare ed eliminare contenuti in modo programmatico, usando i metodi HTTP standard (GET, POST, PUT, DELETE) e il formato JSON per lo scambio dei dati.

La REST API è integrata in WordPress dalla versione 4.7 (dicembre 2016) e rappresenta il modo moderno di interagire con WordPress. Viene usata per app mobile che mostrano contenuti WordPress, frontend JavaScript (React, Vue, Angular) che usano WordPress come backend, integrazioni con servizi esterni e automazione della gestione dei contenuti. L'editor Gutenberg, l'editor standard di WordPress dalla versione 5.0, usa intensamente la REST API per tutte le operazioni sui contenuti. Se hai appena iniziato, consulta la nostra guida all'installazione di WordPress.

Le basi della REST API

Endpoint e route

La REST API di WordPress è disponibile sul tuo sito sotto il percorso /wp-json/. Usando un browser o uno strumento come cURL o Postman, puoi accedere all'API. Per esempio, una richiesta GET a /wp-json/wp/v2/posts restituisce un elenco di articoli in formato JSON, /wp-json/wp/v2/pages restituisce le pagine, /wp-json/wp/v2/categories restituisce le categorie, /wp-json/wp/v2/users restituisce gli utenti, /wp-json/wp/v2/media restituisce i file multimediali e /wp-json/wp/v2/comments restituisce i commenti. Ognuno di questi endpoint supporta diversi metodi HTTP per diverse operazioni: GET per la lettura, POST per la creazione, PUT/PATCH per l'aggiornamento e DELETE per l'eliminazione.

Parametri di query

La REST API supporta numerosi parametri per filtrare e impaginare i risultati. Il parametro per_page controlla il numero di risultati per pagina (predefinito 10, massimo 100), page specifica la pagina di risultati per l'impaginazione, search cerca nei contenuti per parola chiave, orderby definisce il campo di ordinamento (date, title, id), order definisce la direzione di ordinamento (asc o desc), mentre categories e tags filtrano per categoria o tag. Per esempio, la richiesta /wp-json/wp/v2/posts?per_page=5&categories=3&orderby=date&order=desc restituisce i 5 articoli più recenti della categoria con ID 3.

Struttura della risposta

L'API restituisce i dati in formato JSON. Ogni oggetto articolo contiene id (identificatore univoco), title con una proprietà rendered (titolo con formattazione HTML), content con una proprietà rendered (contenuto dell'articolo), excerpt con una proprietà rendered (estratto), date (data di pubblicazione nel formato ISO 8601), slug (titolo adatto agli URL), status (publish, draft, pending), author (ID dell'autore), categories e tags (array di ID). Gli header della risposta HTTP contengono metadati utili: X-WP-Total (numero totale di elementi) e X-WP-TotalPages (numero totale di pagine).

Autenticazione

Endpoint pubblici vs protetti

Alcuni endpoint sono disponibili pubblicamente senza autenticazione: la lettura di articoli pubblicati, pagine, categorie e tag. Le operazioni che modificano i dati (creazione, aggiornamento, eliminazione) e l'accesso ai dati privati richiedono l'autenticazione. La REST API di WordPress supporta diversi metodi di autenticazione a seconda del contesto d'uso.

Application Password

Dalla versione 5.6 di WordPress, le Application Password sono integrate nel core e rappresentano il modo più semplice per autenticare le applicazioni esterne. Crei una Application Password per un utente in Utenti → Profilo → Application Passwords. La password generata si usa con l'autenticazione HTTP Basic: invii il nome utente e la application password nell'header Authorization di ogni richiesta. Le Application Password hanno il vantaggio di poter essere revocate singolarmente senza cambiare la password principale dell'utente.

Autenticazione JWT

Il JSON Web Token (JWT) è un metodo di autenticazione popolare nelle single-page application e nelle app mobile. WordPress non ha il supporto JWT integrato, ma plugin come JWT Authentication for WP REST API o Simple JWT Login aggiungono questa funzionalità. Il client invia nome utente e password all'endpoint del token, ottiene un token JWT e poi lo invia nell'header Authorization come Bearer token con ogni richiesta. I token JWT hanno una durata limitata e possono essere rinnovati senza reinviare la password.

OAuth 2.0

OAuth 2.0 è lo standard di settore per l'autorizzazione che consente a terze parti di accedere alle risorse senza condividere le password. WordPress supporta OAuth tramite il plugin OAuth Server. OAuth è ideale per le applicazioni che accedono ai contenuti WordPress per conto di un utente: l'utente autorizza l'applicazione attraverso la pagina di login di WordPress, l'applicazione riceve un access token e lo usa per le chiamate API. È il metodo più sicuro per le applicazioni in produzione.

Creazione di endpoint personalizzati

Register REST Route

WordPress ti consente di creare endpoint API personalizzati per le esigenze specifiche della tua applicazione. Usa la funzione register_rest_route() nell'hook rest_api_init. Definisci il namespace (ad esempio myplugin/v1), la route (ad esempio /featured-posts), il metodo HTTP (GET, POST), una funzione di callback che restituisce i dati e una funzione opzionale permission_callback per il controllo degli accessi. Gli endpoint personalizzati sono utili per dati che richiedono query complesse, aggregazioni o trasformazioni che gli endpoint standard non supportano.

Permission Callback

La funzione permission callback controlla chi può accedere all'endpoint. Per gli endpoint pubblici, usa __return_true. Per gli endpoint protetti, verifica i permessi dell'utente usando la funzione current_user_can(). Per esempio, un endpoint per la creazione di articoli dovrebbe verificare current_user_can('publish_posts'). Non lasciare mai gli endpoint di scrittura senza un permission callback, perché ciò espone il sito agli abusi.

Validazione e sanitizzazione dei parametri

Gli endpoint personalizzati dovrebbero definire gli argomenti con validazione e sanitizzazione. Per ogni parametro definisci required (se è obbligatorio), type (string, integer, boolean), validate_callback (funzione che verifica la validità del valore) e sanitize_callback (funzione che pulisce il valore prima dell'uso). WordPress offre funzioni di sanitizzazione integrate come sanitize_text_field(), absint() e sanitize_email(). Una validazione corretta previene errori inattesi e vulnerabilità di sicurezza.

WordPress headless

Il concetto di CMS headless

WordPress headless è un'architettura in cui WordPress viene usato solo come backend (CMS) per la gestione dei contenuti, mentre la visualizzazione frontend gira in un'applicazione completamente separata. La REST API di WordPress funge da ponte tra backend e frontend. Il frontend può essere costruito con React, Vue.js, Next.js, Nuxt, Angular o qualsiasi altro framework. I vantaggi sono il pieno controllo del frontend, prestazioni migliori (pagine statiche invece del rendering PHP di WordPress), la possibilità di usare gli stessi contenuti su un sito web, un'app mobile e altre piattaforme e un'esperienza di sviluppo moderna (hot reloading, architettura a componenti).

Next.js e WordPress

La combinazione di Next.js e WordPress è una delle implementazioni headless più popolari. Next.js fornisce il server-side rendering (SSR), la generazione di siti statici (SSG) e la rigenerazione statica incrementale (ISR), ottenendo siti estremamente veloci. I contenuti vengono recuperati dalla REST API di WordPress durante il build (per l'SSG) o su richiesta (per l'SSR). Il componente Image di Next.js ottimizza automaticamente le immagini e il sistema di routing mappa gli slug di WordPress sulle pagine. Molti grandi siti usano questa combinazione per le sezioni blog, mentre il resto del sito usa componenti personalizzati.

Le sfide dell'headless

WordPress headless non è privo di sfide. Hai perso i temi di WordPress e il personalizzatore visivo: tutto deve essere programmato nel framework frontend. I plugin che generano output frontend (form di contatto, gallerie, page builder) non funzionano in modalità headless. La funzionalità di anteprima richiede una configurazione aggiuntiva. I plugin SEO come Yoast generano i metadati, ma il frontend deve recuperarli e visualizzarli correttamente. Commenti, ricerca e impaginazione devono essere implementati sul frontend tramite chiamate API. L'approccio headless richiede un team con esperienza di sviluppo frontend.

Sicurezza della REST API

Limitare l'accesso

Per impostazione predefinita, la REST API di WordPress è disponibile pubblicamente e rivela informazioni su utenti, articoli e struttura del sito. Per un sito che non usa l'API, valuta di limitare l'accesso. Puoi disabilitare la REST API per gli utenti non autenticati usando il filtro rest_authentication_errors, bloccare endpoint specifici (in particolare /wp/v2/users che rivela i nomi utente) oppure usare un plugin come Disable WP REST API per una disattivazione selettiva. Non bloccare mai del tutto la REST API se usi l'editor Gutenberg, perché dipende dall'API.

Rate Limiting

Una REST API senza rate limiting può essere abusata per attacchi brute force, scraping dei contenuti o DDoS. Implementa il rate limiting a livello di server web (modulo limit_req di Nginx, mod_ratelimit di Apache) o tramite regole WAF. Cloudflare Rate Limiting è una soluzione semplice: limita l'endpoint /wp-json/ a un numero ragionevole di richieste al minuto (ad esempio 60 per gli utenti autenticati, 30 per quelli non autenticati).

Strumenti utili per lavorare con la REST API

• Postman: uno strumento grafico per testare le chiamate API con supporto per tutti i metodi HTTP, l'autenticazione e le collezioni di richieste.
• cURL: uno strumento da riga di comando per le richieste HTTP, ideale per test rapidi e scripting.
• Insomnia: un'alternativa moderna a Postman con un'interfaccia pulita e supporto GraphQL.
• WP-CLI: lo strumento da riga di comando di WordPress che internamente usa la REST API e ti permette di gestire il sito dal terminale.
• Thunder Client: un'estensione di VS Code per testare le API direttamente dall'editor.

Conclusione

La REST API di WordPress apre nuove possibilità di utilizzo di WordPress oltre il tradizionale blog o sito. Che tu stia costruendo un'app mobile, un frontend JavaScript o integrando WordPress con altri sistemi, la REST API offre un modo standardizzato e documentato per accedere ai contenuti. Per i progetti headless, la combinazione di WordPress e un framework frontend moderno come Next.js offre il meglio di entrambi i mondi: gestione dei contenuti semplice e prestazioni di alto livello. Su BeoHosting, tutti i piani di hosting WordPress supportano la REST API con configurazioni PHP e MySQL ottimizzate per risposte API più rapide.