WP REST API, headless y endpoints personalizados

Sin embargo, trabajar de forma profesional con la WP REST API exige ir mucho más allá de simples peticiones GET /wp/v2/posts. Una arquitectura empresarial requiere rutas propias para la lógica de negocio personalizada, un control riguroso de las autorizaciones, validación declarativa de los tipos de datos y estrategias sólidas para reducir la latencia. En esta guía técnica de ingeniería repasamos todos los aspectos prácticos para ampliar y proteger tu infraestructura REST en WordPress.

#Por qué los endpoints nativos /wp/v2/ no siempre bastan

La API pública nativa bajo el namespace /wp-json/wp/v2/ cubre entradas, páginas, categorías, etiquetas y metadatos. Para escenarios de lectura simples funciona desde el primer momento. Pero, a medida que crece la complejidad de la aplicación, aparecen tres limitaciones críticas:

1. Exceso de datos transferidos (over-fetching): una petición a /wp/v2/posts devuelve decenas de campos auxiliares, enlaces HAL, objetos de autor y datos de comentarios que un componente ligero del frontend a menudo no necesita.
2. Consultas en cascada (under-fetching / N+1): si necesitas los datos de una entrada, el producto de WooCommerce asociado y las valoraciones de los usuarios, la API estándar obliga al frontend a hacer varias peticiones consecutivas, lo que multiplica la latencia de red.
3. Exposición de la lógica de dominio: las reglas de negocio complejas (como calcular presupuestos en tiempo real, comprobar el stock en un almacén externo o validar formularios de varios pasos) no pertenecen al cliente frontend; deben encapsularse en un endpoint específico en el servidor.

La respuesta arquitectónica correcta es registrar rutas propias con la función register_rest_route().

#Cómo crear un endpoint personalizado en la WordPress REST API

Toda interacción personalizada con la REST API debe registrarse en el hook de acción rest_api_init. Crear rutas fuera de este hook puede provocar errores de carga prematura y fallos de compatibilidad con plugins de seguridad.

La firma estándar de la función es la siguiente:

register_rest_route( string $namespace, string $route, array $args = array(), bool $override = false ): bool

#Namespace y versionado de las rutas REST

El $namespace funciona como prefijo identificador de tu proyecto o plugin (por ejemplo, wppoland/v1). Es una regla estricta de buenas prácticas: nunca registres endpoints directamente bajo el namespace del núcleo wp/v2. Crear tus rutas bajo tu propio namespace con versionado explícito garantiza que los futuros cambios en el esquema de datos puedan convivir con versiones anteriores (wppoland/v2) sin romper aplicaciones móviles ni clientes externos ya desplegados.

El $route es la ruta del recurso después del namespace y admite expresiones regulares con el formato de grupos con nombre de PHP ((?P<parametro>[a-zA-Z0-9-]+)).

#Ejemplo de register_rest_route() para una lista ligera de entradas

Imagina un escenario en el que un frontend estático en Astro necesita una lista ultraligera de destacados editoriales, con solo el identificador, el título, el extracto saneado y el tiempo estimado de lectura:

<?php
/**
 * Plugin Name: WPPoland REST Core
 * Description: Endpoints dedicados para una integración headless de alto rendimiento.
 */

declare(strict_types=1);

add_action('rest_api_init', function (): void {
    register_rest_route('wppoland/v1', '/destaques', [
        'methods'             => WP_REST_Server::READABLE, // Equivale a 'GET'
        'callback'            => 'wppoland_obter_destaques_callback',
        'permission_callback' => '__return_true', // Ruta pública
        'args'                => [
            'limite' => [
                'description'       => 'Número máximo de registros que se devuelven.',
                'type'              => 'integer',
                'default'           => 6,
                'minimum'           => 1,
                'maximum'           => 20,
                'sanitize_callback' => 'absint',
                'validate_callback' => function ($param, $request, $key) {
                    return rest_validate_request_arg($param, $request, $key);
                },
            ],
            'categoria' => [
                'description'       => 'Slug de la categoría para el filtrado temático.',
                'type'              => 'string',
                'required'          => false,
                'sanitize_callback' => 'sanitize_title',
            ],
        ],
    ]);
});

/**
 * Callback de ejecución de la ruta /destaques.
 *
 * @param WP_REST_Request $request Objeto de la petición HTTP.
 * @return WP_REST_Response|WP_Error
 */
function wppoland_obter_destaques_callback(WP_REST_Request $request): WP_REST_Response {
    $limite = (int) $request->get_param('limite');
    $categoria = (string) $request->get_param('categoria');

    $args_query = [
        'post_type'              => 'post',
        'post_status'            => 'publish',
        'posts_per_page'         => $limite,
        'no_found_rows'          => true, // Desactiva el cálculo de paginación para máximo rendimiento
        'update_post_meta_cache' => false,
        'update_post_term_cache' => false,
        'fields'                 => 'ids',
    ];

    if (!empty($categoria)) {
        $args_query['category_name'] = $categoria;
    }

    $query = new WP_Query($args_query);
    $itens = [];

    foreach ($query->posts as $post_id) {
        $post = get_post($post_id);
        if (!$post) {
            continue;
        }

        $palavras = str_word_count(wp_strip_all_tags($post->post_content));
        $tempo_leitura = (int) ceil($palavras / 200); // 200 palabras por minuto

        $itens[] = [
            'id'            => $post->ID,
            'titulo'        => get_the_title($post),
            'resumo'        => wp_trim_words($post->post_excerpt ?: $post->post_content, 25),
            'tempo_leitura' => max(1, $tempo_leitura),
            'url_canonica'  => get_permalink($post),
        ];
    }

    $resposta = new WP_REST_Response($itens, 200);
    // Añadir cabecera de caché para proxies en el edge
    $resposta->header('Cache-Control', 'public, max-age=300, s-maxage=600');

    return $resposta;
}

#Validar y sanear parámetros en la REST API de WordPress

Uno de los errores más frecuentes al implementar endpoints en WordPress es procesar los parámetros directamente dentro del callback sin validarlos antes. La arquitectura de la REST API ofrece un mecanismo riguroso a través del array args:

1. validate_callback: comprueba si el tipo de dato recibido cumple el contrato esperado antes de invocar la lógica principal. Si devuelve false o un WP_Error, WordPress interrumpe el ciclo de vida y devuelve automáticamente un código 400 Bad Request.
2. sanitize_callback: transforma y limpia el valor de entrada (p. ej. sanitize_text_field, absint, esc_url_raw) antes de entregarlo al callback.

La validación comprueba el contrato de entrada. Las consultas SQL siguen necesitando prepared statements y el HTML escaping adecuado al contexto.

#Cómo proteger endpoints REST con permission_callback

Desde WordPress 5.5, omitir el parámetro permission_callback al registrar una ruta genera un aviso de seguridad explícito _doing_it_wrong(). Cada endpoint debe definir de forma expresa su política de autorización:

• Para endpoints totalmente públicos: declara 'permission_callback' => '__return_true'.
• Para endpoints restringidos a usuarios autenticados: comprueba las capacidades nativas de WordPress con current_user_can().

register_rest_route('wppoland/v1', '/lead-submissao', [
    'methods'             => WP_REST_Server::CREATABLE, // 'POST'
    'callback'            => 'wppoland_salvar_lead_callback',
    'permission_callback' => function (WP_REST_Request $request): bool|WP_Error {
        // Ejemplo: solo editores o administradores pueden ver informes
        if (!current_user_can('edit_posts')) {
            return new WP_Error(
                'rest_forbidden',
                'No tienes permisos suficientes para enviar o consultar estos datos.',
                ['status' => 403]
            );
        }
        return true;
    },
]);

#Nonces, Application Passwords o JWT en la REST API

Cuando sistemas externos se comunican con la REST API, existen tres patrones fundamentales de autenticación:

1. Nonces de WordPress (sesiones en el mismo dominio): Se usan cuando el JavaScript se ejecuta en el mismo origen web (por ejemplo, bloques interactivos de Gutenberg o paneles de administración personalizados). El frontend incluye la cabecera X-WP-Nonce generada por wp_create_nonce('wp_rest') y la autenticación se basa en las cookies de sesión del usuario.
2. Application Passwords (nativas desde WP 5.6): Ideales para integraciones máquina a máquina (scripts de sincronización, webhooks de facturación o bots de publicación). Cada usuario puede crear claves de acceso independientes en la sección Perfil del escritorio. El cliente HTTP envía la cabecera Authorization: Basic base64(usuario:contrasena-aplicacion). Es obligatorio que el tráfico vaya por HTTPS para impedir que se intercepten las credenciales.
3. Autenticación con JWT (JSON Web Tokens): Una opción que requiere un plugin de autenticación revisado para usuarios de frontends totalmente desacoplados (Single Page Applications en React o aplicaciones móviles). El usuario inicia sesión en el endpoint de autenticación, recibe un token firmado con validez temporal y lo adjunta a cada petición posterior mediante la cabecera Authorization: Bearer <token>.

#Cómo acelerar la WordPress REST API

Una petición a la WordPress REST API no es una llamada ligera como un script estático en Go o Node.js: cada llamada HTTP a la API inicializa todo el ecosistema de WordPress (wp-load.php, inicialización de plugins, carga de traducciones y configuración del tema).

Para evitar que una aplicación frontend se vuelva lenta al consumir datos del CMS, se aplican tres técnicas probadas:

#1. Filtrado de campos con el parámetro _fields

Al consumir rutas nativas, indica al cliente HTTP que pida solo los campos necesarios. El parámetro _fields hace que WordPress descarte el procesamiento del resto de nodos del objeto antes de serializar el JSON:

# Request only the fields needed by the client.
GET /wp-json/wp/v2/posts?_fields=id,slug,title

#2. Caché con la Transients API o Redis Object Cache

En endpoints que agregan datos complejos o hacen cálculos pesados, guarda la respuesta calculada en la memoria caché:

function wppoland_obter_dados_agregados(): array {
    $chave_cache = 'wppoland_relatorio_mensal';
    $dados = get_transient($chave_cache);

    if (false === $dados) {
        // Ejecutar las consultas pesadas
        $dados = wppoland_computar_metricas_complexas();
        // Guardar en caché durante 1 hora (3600 segundos)
        set_transient($chave_cache, $dados, 3600);
    }

    return $dados;
}

Cuando se publica una entrada nueva o cambia el inventario, usa el hook save_post para invalidar selectivamente el transient con delete_transient().

#3. Cabeceras de caché HTTP para CDN y proxies en el edge

Añadir cabeceras Cache-Control a las respuestas de las rutas GET permite que servicios en el edge como Cloudflare, o servidores FastCGI locales, entreguen el JSON directamente desde memoria, sin arrancar el intérprete de PHP en las peticiones repetidas.

#Preguntas frecuentes (FAQ)

#Un contrato de respuesta para varias aplicaciones

Empieza por los datos que necesita el consumidor. Una lista editorial puede devolver entradas publicadas, pero una integración ERP también necesita identificadores estables, fechas de modificación y una forma documentada de reanudar una importación interrumpida. Define la diferencia entre una colección vacía, un recurso inexistente y un fallo temporal del origen. Cada situación requiere una reacción distinta. Una consulta sin resultados puede tener éxito. Un error de base de datos no debe convertirse en una lista vacía que provoca el borrado de productos en el sistema receptor.

Documenta si un campo admite null, una cadena vacía o su ausencia. Un producto sin imagen no equivale a un producto sin publicar. El identificador permanece estable cuando el editor cambia el slug. Los códigos de error deben ser independientes de las traducciones, para que una tienda española y un panel inglés reconozcan el mismo problema. Define la zona horaria y si los importes incluyen IVA. Son decisiones de la aplicación que REST no toma automáticamente.

El manual de endpoints personalizados de WordPress describe el registro, los argumentos y los objetos de respuesta. Los ejemplos son una base. Una ruta del proyecto sigue necesitando un esquema de salida y una prueba de integración que compruebe el contrato. Añadir un campo opcional suele mantener la compatibilidad. Cambiar su nombre o tipo requiere una migración. Conserva el namespace anterior mientras lo utilicen aplicaciones ya distribuidas.

#Límites de parámetros y permisos sobre el objeto

Valida el valor original antes de que el saneamiento lo modifique. absint puede convertir una entrada negativa en un número aparentemente válido. Un validate_callback que solo llama a is_numeric también acepta fracciones y números superiores al límite. Utiliza el esquema integer con minimum y maximum, o un wrapper de rest_validate_request_arg cuando necesites reglas adicionales. Prueba cero, negativos, decimales, notación exponencial, arrays y valores fuera del rango. Un control del formulario no limita peticiones HTTP enviadas directamente.

Un usuario autenticado no obtiene acceso a todos los objetos. Para editar una entrada, comprueba una capability específica, como current_user_can('edit_post', $id). Para pedidos WooCommerce, aplica los permisos y la propiedad correspondientes al pedido. La comprobación genérica edit_posts no resuelve el acceso a información del cliente. Una persona que envía el identificador de un pedido ajeno no puede recibir sus datos. Obtén la identidad del contexto autenticado, nunca del identificador de usuario proporcionado en el cuerpo de la petición.

La autenticación mediante cookies necesita la sesión WordPress y el REST nonce. Sin nonce, WordPress trata la petición como anónima; un nonce inválido sigue otro recorrido de error. El nonce no sustituye las capabilities. Application Passwords actúa con los permisos de su usuario y no crea automáticamente scopes comerciales limitados. Crea una cuenta dedicada a la integración, concede los derechos necesarios y guarda la credencial en el servidor. Revoca esa credencial cuando termine la integración. WordPress core no emite JWT de forma nativa: hace falta una implementación adicional revisada. Consulta el manual de autenticación.

#Paginación y límites de la caché

Limita el tamaño de la colección y utiliza un orden determinista. Cuando varios registros comparten la fecha de modificación, usa el identificador estable como segundo criterio. De lo contrario, una importación reanudada puede saltar o repetir registros. Offset sirve para una lista editorial pequeña. Un catálogo que cambia continuamente puede necesitar un cursor definido por la aplicación. Describe qué ocurre al eliminar un producto y cómo reconoce el cliente la última página. No anuncies un total deducido de la página actual cuando no_found_rows desactiva el recuento.

La clave de caché incluye todos los factores que alteran el resultado: filtros normalizados, idioma, página o cursor, selección de campos y grupo de clientes cuando corresponda. Una caché pública del catálogo excluye borradores, metadatos privados y precios individuales. Para cuentas y pedidos, empieza con Cache-Control: private, no-store y configura la exclusión de la ruta en el edge. Prueba a través del proxy real con dos usuarios. Un encabezado PHP correcto no repara una regla de CDN demasiado amplia.

Los transients pueden almacenarse en la base de datos o en una caché externa de objetos. Pueden desaparecer antes de expirar, por lo que la aplicación necesita reconstruir el resultado de forma segura. La invalidación cubre borrado, cambios de estado y modificaciones de taxonomías relacionadas. Una actualización de stock puede suceder fuera de save_post; utiliza los eventos de la integración comercial efectiva. Los encabezados por sí solos no garantizan que Cloudflare almacene JSON. Verifica la regla, la clave y los estados observados en el entorno de destino.

#Pruebas y evidencia operativa

Prueba las rutas con WP_REST_Request y rest_do_request en un entorno de pruebas WordPress. Incluye lectura pública, argumentos incorrectos, ausencia de credencial, una cuenta válida sin permisos y una cuenta autorizada para ese objeto. Comprueba estado HTTP, estructura y encabezados de caché. Añade un registro sin publicar a los datos de prueba y confirma que no aparece en resultados anónimos. Para una ruta de escritura, verifica que la petición rechazada no modifica la base de datos.

Mide por separado las peticiones con caché fría y caliente. Registra tiempo de base de datos, número de consultas, tamaño de respuesta y espera del servicio externo de almacén. _fields puede reducir transferencia y preparación de campos compatibles, pero el efecto depende de la ruta. No sustituye consultas selectivas. La documentación de parámetros globales explica el mecanismo. Presenta mediciones del propio entorno en lugar de prometer un porcentaje universal de mejora.

Las peticiones externas requieren timeout y una respuesta de fallo definida. Repite lecturas con un número limitado de intentos y pausas. Repite escrituras solo cuando el receptor ofrece idempotencia o un contrato equivalente de detección de duplicados. Registra identificador de correlación, ruta, estado y duración. Contraseñas, tokens, direcciones de clientes y cuerpos completos no pertenecen a los logs corrientes. Tras publicar, prueba el hostname de producción junto con el reverse proxy. Las pruebas PHP no incluyen toda la cadena de entrega.

#Conclusión

La WordPress REST API eleva el CMS al nivel de un verdadero framework de gestión y distribución de datos. Al estructurar rutas especializadas con register_rest_route(), validar las entradas con rigor y aplicar políticas de caché bien pensadas, consigues que tu aplicación desacoplada combine la flexibilidad editorial de WordPress con la velocidad de la web actual.

¿Quieres migrar tu web a una arquitectura moderna y desacoplada? Conoce mis servicios de migración a Astro y Next.js o mi trabajo como desarrollador WordPress.