La REST API di WordPress: cos'è e come usarla

Tu WordPress no es solo una web: también es un servidor de datos. Desde la versión 4.7, la REST API de WordPress viene integrada en el núcleo y expone entradas, páginas, usuarios, medios y taxonomías en formato JSON, listos para ser leídos o modificados desde cualquier aplicación externa: una app móvil, un script de automatización, otra web o un panel de control a medida. Es la tecnología que hace funcionar el editor de bloques, la que usan miles de integraciones y la puerta de entrada al llamado WordPress «headless». Y, sin embargo, muchos usuarios avanzados no la han explorado nunca. En esta guía práctica veremos qué es exactamente la REST API de WordPress, cómo están organizados sus endpoints, cómo autenticarte de forma segura con Application Passwords, cómo leer y crear contenido con ejemplos reales (desde el navegador, con JavaScript y con PHP), cómo crear tus propios endpoints y qué precauciones de seguridad conviene tomar. Todo con código funcional que puedes probar hoy en tu propia web.

Qué es la REST API de WordPress y para qué sirve

Una API REST es una interfaz que permite a dos sistemas comunicarse sobre HTTP usando las operaciones clásicas del protocolo: GET para leer, POST para crear, PUT/PATCH para actualizar y DELETE para borrar. La respuesta llega en JSON, un formato de texto ligero que cualquier lenguaje entiende. En el caso de WordPress, eso significa que todo lo que gestionas desde el escritorio (entradas, páginas, comentarios, categorías, usuarios, medios) tiene también una «puerta trasera» estructurada y oficial para máquinas.

Casos de uso reales donde la REST API de WordPress marca la diferencia:

• Automatización: publicar o actualizar contenido desde scripts, hojas de cálculo o herramientas como n8n y Make.
• Headless WordPress: usar WordPress solo como gestor de contenido y montar el frontend con React, Vue o Astro.
• Apps móviles: la app oficial de WordPress funciona íntegramente sobre esta API.
• Integraciones entre webs: mostrar en una web los últimos artículos de otra, sincronizar catálogos, centralizar publicación.
• Paneles a medida: dashboards que leen y escriben en WordPress sin pasar por wp-admin.

La API es también la base de integraciones modernas con inteligencia artificial: plugins como AI Engine, que convierte tu WordPress en un agente de IA, se apoyan en ella para exponer el contenido a asistentes externos.

Endpoints principales: el mapa de la API

Todo empieza en una URL: https://tudominio.com/wp-json/. Ábrela en el navegador y verás el índice completo de rutas disponibles. Los endpoints del núcleo cuelgan del espacio de nombres wp/v2:

Cada endpoint de colección admite parámetros de consulta muy útiles: ?per_page=5 limita resultados, ?search=wordpress busca, ?categories=12 filtra por categoría, ?orderby=date&order=asc ordena y ?_fields=id,title,link devuelve solo los campos que pidas, aligerando la respuesta. Para un elemento concreto se añade su ID: /wp-json/wp/v2/posts/123.

Las respuestas JSON de WordPress llegan sin formato, en una sola línea difícil de leer. Un truco de flujo de trabajo: pega la respuesta en nuestro formateador y validador JSON gratuito y tendrás el árbol indentado y coloreado para inspeccionarlo con comodidad.

Paginación: las cabeceras que debes conocer

Los endpoints de colección devuelven como máximo 100 elementos por petición (10 por defecto). Para recorrer catálogos grandes, la API incluye en cada respuesta dos cabeceras HTTP: X-WP-Total, con el número total de elementos, y X-WP-TotalPages, con el número de páginas disponible según tu per_page. Basta con iterar añadiendo ?page=2, ?page=3 e così via fino a raggiungere l'ultima. Se richiedi una pagina inesistente, l'API risponde con un errore 400 con il codice rest_post_invalid_page_number, un segnale comodo per fermare il ciclo negli script di esportazione o migrazione.

Autenticazione con Password per le applicazioni

Leggere contenuti pubblici non richiede l'identificazione, ma creare, modificare o eliminare sì. Da WordPress 5.6 il metodo integrato e raccomandato sono le Password per le applicazioni (password per le applicazioni): chiavi specifiche per ogni applicazione, revocabili individualmente e che non espongono la tua password reale.

Per crearne una: entra in Utenti → Profilo, scorri fino a «Password dell'applicazione», scrivi un nome descrittivo (ad esempio «Script di pubblicazione») e premi crea. WordPress ti mostrerà una sola volta una chiave con il formato xxxx xxxx xxxx xxxx xxxx xxxx. Salvala in un gestore di password o in un file di variabili d'ambiente, mai nel codice sorgente.

La chiave viene usata con autenticazione HTTP Basic: utente e password dell'applicazione codificati in Base64 nell'intestazione Authorization. Requisito indispensabile: il sito web deve essere servito tramite HTTPS, perché in HTTP semplice le credenziali viaggerebbero esposte.

Test rapido dal terminale con curl:

curl -X POST https://tudominio.com/wp-json/wp/v2/posts \
  -u "tu_usuario:xxxx xxxx xxxx xxxx xxxx xxxx" \
  -H "Content-Type: application/json" \
  -d '{"title":"Borrador desde la API","status":"draft"}'

Se la risposta è un JSON con l'ID della nuova bozza, l'autenticazione funziona. Ogni permesso dipende dal ruolo dell'utente: una password dell'applicazione di un sottoscrittore non potrà pubblicare post.

Leggere e creare contenuti: esempi con JavaScript

Vediamo l'API in azione con fetch, proprio come faresti in un sito web esterno o un'applicazione. Per prima cosa, leggi gli ultimi articoli di un blog (senza autenticazione, contenuto pubblico):

const API = 'https://tudominio.com/wp-json/wp/v2';

async function ultimasEntradas() {
  const res = await fetch(`${API}/posts?per_page=5&_fields=id,title,link,date`);
  if (!res.ok) {
    throw new Error('Error HTTP ' + res.status);
  }
  const posts = await res.json();
  posts.forEach((post) => {
    console.log(`${post.date} — ${post.title.rendered} — ${post.link}`);
  });
}

ultimasEntradas();

E ora, creare un post autenticandoci con una Application Password (questo deve essere eseguito in un ambiente server o script privato, mai nel browser dei tuoi visitatori, perché esporrebbe la chiave):

const usuario = 'tu_usuario';
const clave   = 'xxxx xxxx xxxx xxxx xxxx xxxx';
const token   = Buffer.from(`${usuario}:${clave}`).toString('base64');

async function crearEntrada() {
  const res = await fetch('https://tudominio.com/wp-json/wp/v2/posts', {
    method: 'POST',
    headers: {
      'Authorization': `Basic ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      title: 'Publicado por la REST API',
      content: '<p>Este contenido lo ha creado un script.</p>',
      status: 'draft',
      categories: [12],
    }),
  });
  const data = await res.json();
  if (!res.ok) {
    throw new Error(data.message || 'Error al crear la entrada');
  }
  console.log('Creada con ID', data.id, '→', data.link);
}

crearEntrada();

Fai attenzione al dettaglio di title.rendered durante la lettura: l'API restituisce i campi di testo come oggetti con le varianti rendered (HTML finale) e, se sei autenticato con permessi di modifica e aggiungi ?context=edit, anche raw (contenuto originale).

Creare i tuoi endpoint con register_rest_route

L'API del core copre il contenuto standard, ma il vero potenziale si raggiunge quando esponi i tuoi dati. Con register_rest_route() puoi creare percorsi personalizzati sotto il tuo namespace. Esempio completo: un endpoint che restituisce statistiche di base del sito, con un parametro validato e controllo dei permessi:

<?php
add_action( 'rest_api_init', function () {
    register_rest_route( 'biblioweb/v1', '/estadisticas', array(
        'methods'             => 'GET',
        'callback'            => 'biblioweb_api_estadisticas',
        'permission_callback' => '__return_true', // Endpoint público de solo lectura.
        'args'                => array(
            'tipo' => array(
                'default'           => 'post',
                'sanitize_callback' => 'sanitize_key',
                'validate_callback' => function ( $valor ) {
                    return post_type_exists( $valor );
                },
            ),
        ),
    ) );
} );

function biblioweb_api_estadisticas( WP_REST_Request $request ) {
    $tipo     = $request->get_param( 'tipo' );
    $conteo   = wp_count_posts( $tipo );
    $usuarios = count_users();

    return rest_ensure_response( array(
        'tipo'        => $tipo,
        'publicados'  => (int) $conteo->publish,
        'borradores'  => (int) $conteo->draft,
        'usuarios'    => (int) $usuarios['total_users'],
        'generado_en' => current_time( 'mysql' ),
    ) );
}

Dopo aver salvato questo codice (in un plugin o snippet), il tuo nuovo endpoint risponde in https://tudominio.com/wp-json/biblioweb/v1/estadisticas?tipo=page. Tre regole d'oro: usa sempre un namespace proprio con versione (biblioweb/v1), definisci permission_callback esplicitamente (è obbligatorio da WordPress 5.5; per gli endpoint privati usa un controllo come current_user_can( 'edit_posts' )) e valida ogni parametro di input. Il riferimento completo si trova nel manuale ufficiale della REST API di WordPress.

Sicurezza: cosa esporre e cosa proteggere

La REST API di WordPress è sicura per design (espone solo ciò che è già pubblico e richiede permessi per scrivere), ma è opportuno regolare alcuni dettagli:

• Enumerazione degli utenti: l'endpoint /wp/v2/users elenca gli autori con contenuti pubblicati, il che facilita a un attaccante la conoscenza di nomi utente validi. Molti plugin di sicurezza lo limitano; può anche essere filtrato tramite codice per richiedere autenticazione.
• HTTPS obbligatorio: senza certificato SSL, le Application Passwords viaggiano in chiaro. Non c'è un'eccezione ragionevole a questa regola.
• Principio del minimo privilegio: crea le password dell'applicazione con un utente il cui ruolo abbia solo i permessi necessari all'integrazione, e revoca le password quando non sono più in uso.
• Non disattivare l'API brutalmente: l'editor a blocchi e molti plugin dipendono da essa. Se vuoi limitarla, richiedi l'autenticazione con il filtro rest_authentication_errors invece di bloccarla completamente.
• Limita la superficie: gli endpoint personalizzati pubblici devono restituire solo dati che non ti importa siano visibili a chiunque.

Queste precauzioni rientrano in una strategia generale di hardening; se vuoi ripassarla, abbiamo una guida con trucchi per rafforzare la sicurezza del tuo WordPress.

Domande frequenti

La REST API di WordPress è attiva sul mio sito web?

Quasi sicuramente, sì: è attiva di default da WordPress 4.7 (2016). Controllalo visitando tudominio.com/wp-json/: se vedi un JSON con il nome del tuo sito e l'elenco dei percorsi, è operativa. Se restituisce un 404, controlla i permalink o qualche plugin di sicurezza che la stia bloccando.

È pericoloso avere l'API attivata?

Non più che avere il sito web pubblicato. L'API di lettura espone solo contenuti già pubblici sul tuo sito, e ogni operazione di scrittura richiede autenticazione e permessi. Le due impostazioni sensate sono limitare l'elenco degli utenti e assicurarsi di servire tutto tramite HTTPS. Disattivarla completamente di solito causa più problemi di quanti ne eviti.

Posso usare l'API con custom post type e campi personalizzati?

Sì. I custom post type appaiono nell'API se sono stati registrati con show_in_rest => true, e ottengono il proprio endpoint (ad esempio /wp/v2/proyecto). I campi personalizzati vengono esposti con register_post_meta() spuntando anche show_in_rest, o con il campo meta del post stesso se il plugin che li crea lo supporta.

Che differenza c'è tra la REST API e WPGraphQL?

La REST API è lo standard del core: ogni tipo di dato ha il suo endpoint e le risposte hanno una struttura fissa. GraphQL (tramite il plugin WPGraphQL) permette di richiedere esattamente i campi di cui hai bisogno in una singola query, cosa apprezzata nei progetti headless complessi. Per automazioni, integrazioni e la maggior parte dei progetti, la REST API è più semplice, non richiede plugin ed è supportata ufficialmente.

Conclusión

La REST API di WordPress trasforma il tuo sito web in una piattaforma programmabile: un indice chiaro di endpoint sotto /wp-json/wp/v2/, autenticazione integrata con Application Passwords su HTTPS e la possibilità di ampliare la mappa con percorsi propri tramite register_rest_route(). Con quanto visto in questa guida puoi leggere contenuti pubblici da qualsiasi applicazione, pubblicare e modificare tramite script autenticati, esporre dati personalizzati con validazione e permessi, e farlo con le adeguate precauzioni di sicurezza. Il modo migliore per interiorizzarla è pratico: apri tudominio.com/wp-json/wp/v2/posts?per_page=3 nel browser, passa la risposta attraverso un formattatore JSON per comprenderne la struttura, crea la tua prima Application Password e lancia una bozza da curl. In quindici minuti avrai varcato la porta che separa l'uso di WordPress dalla programmazione con WordPress.