WPQuery
- Introducción
- ¿Qué es el Abilities API?
- Primeros Pasos: Registrar una Capacidad
- Ejecutar Capacidades
- Casos de Uso Prácticos
- Por Qué Importa el Abilities API
- Conclusión
Introducción
WordPress 6.9 ha traído consigo varias características interesantes, y entre ellas destaca el Abilities API, una nueva forma de definir capacidades en WordPress que pueden ser entendidas tanto por humanos como por máquinas.
El Abilities API proporciona un método estandarizado para que WordPress core, plugins y temas definan sus funcionalidades en un formato estructurado y accesible. Esto es especialmente valioso para herramientas de automatización, agentes de IA y plugins que necesitan descubrir dinámicamente qué puede hacer un sitio WordPress.
¿Qué es el Abilities API?
El Abilities API funciona como un diccionario de capacidades de tu sitio WordPress. Antes de esta API, no existía una manera simple y consistente para que plugins o herramientas externas descubrieran las características disponibles en un sitio.
Las funcionalidades estaban dispersas entre hooks, endpoints de REST API y código personalizado sin una estructura uniforme. Ahora, con el Abilities API, herramientas como agentes de IA (Claude, ChatGPT), Zapier, n8n o cualquier otra aplicación externa pueden simplemente preguntar a WordPress: “¿Qué puedes hacer?” y recibir una lista estructurada de capacidades.
Además, el API facilita la colaboración entre plugins. En lugar de depender de hooks ocultos o soluciones frágiles, los plugins pueden llamar directamente a las capacidades de otros plugins de manera limpia y predecible.
Ventaja clave: El Abilities API es el puente que faltaba entre WordPress y los agentes de IA modernos. Ahora tu sitio puede describir automáticamente qué es capaz de hacer a cualquier herramienta externa.
Primeros Pasos: Registrar una Capacidad
Para utilizar el Abilities API, el primer paso es registrar una nueva capacidad. Esto se realiza normalmente dentro de tu plugin o tema.
Una capacidad debe contener:
- Un nombre único que contenga solo caracteres alfanuméricos en minúsculas, guiones y barras. Por ejemplo:
miempresa/crear-factura - Una descripción legible para humanos y una etiqueta clara
- Esquemas de entrada y salida definidos en JSON Schema
- Una verificación de permisos para controlar quién puede ejecutar la capacidad
Ejemplo 1: Capacidad Simple sin Parámetros
A continuación se muestra un ejemplo de cómo registrar una capacidad simple que devuelve métricas de análisis del sitio:
add_action( 'wp_abilities_api_init', function () {
if ( ! function_exists( 'wp_register_ability' ) ) {
return;
}
wp_register_ability(
'miempresa/resumen-analytics',
[
'label' => __( 'Obtener Resumen de Analytics', 'miplugin' ),
'description' => __( 'Devuelve un resumen de rendimiento del sitio.', 'miplugin' ),
'input_schema' => [
'type' => 'object',
'properties' => [],
],
'output_schema' => [
'type' => 'object',
'properties' => [
'visitas' => [ 'type' => 'integer' ],
'registros' => [ 'type' => 'integer' ],
'ventas' => [ 'type' => 'integer' ],
],
],
'permission_callback' => function () {
return current_user_can( 'manage_options' );
},
'execute_callback' => function () {
return [
'visitas' => 1473,
'registros' => 32,
'ventas' => 5,
];
},
]
);
});
En este ejemplo registramos una capacidad llamada miempresa/resumen-analytics. La capacidad no requiere entrada de parámetros (array vacío en input_schema) pero devuelve un objeto con tres métricas: visitas, registros y ventas. Solo puede ser ejecutada por usuarios con permisos de administración (manage_options).
Ejemplo 2: Capacidad Compleja con Parámetros
Este segundo ejemplo muestra una capacidad más compleja que procesa pedidos. Acepta entrada (ID de cliente, SKUs de productos, token de pago) y devuelve información detallada del pedido creado:
add_action( 'init', function() {
if ( ! function_exists( 'wp_register_ability' ) ) {
return;
}
wp_register_ability( 'miempresa/procesar-pedido', [
'description' => 'Procesa pagos, crea registro de pedido y envía confirmación email.',
'execute_callback' => function ( $inputs ) {
// Implementación de lógica de procesamiento...
},
'input_schema' => [
'type' => 'object',
'properties' => [
'customer_id' => [
'type' => 'integer',
'description' => 'ID del cliente que realiza el pedido.',
],
'product_skus' => [
'type' => 'array',
'description' => 'Array de SKUs de productos a incluir.',
'items' => [ 'type' => 'string' ],
],
'payment_token' => [
'type' => 'string',
'description' => 'Token seguro de un solo uso del gateway.',
],
],
'required' => [ 'customer_id', 'product_skus', 'payment_token' ],
],
'output_schema' => [
'type' => 'object',
'properties' => [
'order_id' => [
'type' => 'integer',
'description' => 'ID del nuevo pedido creado.',
],
'order_status' => [
'type' => 'string',
'description' => 'Estado del pedido (ej: "processing", "pending").',
],
'message' => [
'type' => 'string',
'description' => 'Mensaje de confirmación.',
],
],
],
] );
} );Ejecutar Capacidades
Registrar una capacidad es solo el primer paso. Para que sea útil, también necesitamos ejecutarla y obtener resultados. Hay varias formas de hacerlo según donde estés trabajando.
Ejecutar desde PHP
En PHP, WordPress proporciona la función wp_get_ability() para recuperar una capacidad por su nombre, y luego llamamos al método execute().
Para ejecutar la capacidad simple:
$ability = wp_get_ability( 'miempresa/resumen-analytics' );
if ( $ability ) {
$result = $ability->execute();
}Si la capacidad requiere parámetros (como en el ejemplo de procesar pedido), pasamos un array asociativo al método execute():
$ability = wp_get_ability( 'miempresa/procesar-pedido' );
if ( $ability ) {
$inputs = [
'customer_id' => 123,
'product_skus' => [ 'SKU123', 'SKU456' ],
'payment_token'=> 'tok_1A2B3C****',
];
$result = $ability->execute( $inputs );
}Una ventaja importante es que no necesitas manejar manualmente verificaciones de permisos ni validación de entrada. El método execute() se encarga automáticamente de validar los parámetros según los esquemas definidos y de verificar los permisos. Si algo no es correcto, la ejecución falla de forma segura.
Ejecutar desde JavaScript / REST API
El Abilities API también soporta REST API de forma integrada. Sin embargo, necesitas habilitar show_in_rest al registrar la capacidad:
'meta' => [
'show_in_rest' => true,
]Una vez habilitado, la capacidad estará disponible en el endpoint REST: /wp-json/wp-abilities/v1/miempresa/resumen-analytics. Las aplicaciones externas o tu código frontend pueden ejecutar capacidades enviando peticiones HTTP sin necesidad de escribir código REST personalizado.
WordPress también está introduciendo una librería cliente de JavaScript para el Abilities API que simplifica significativamente las llamadas desde el navegador. Primero, instala la librería:
npm i @wordpress/abilitiesLuego, úsala en tu aplicación JavaScript (React):
useEffect(() => {
executeAbility( 'miempresa/resumen-analytics' ).then( ( response ) => {
setResponse( response ); // Guardar resultado
} );
}, []);Casos de Uso Prácticos
El Abilities API abre muchas posibilidades interesantes:
- Integración con Agentes de IA: Claude, ChatGPT o n8n pueden descubrir automáticamente qué acciones realizar en tu sitio sin necesidad de configuración manual.
- Automatización entre plugins: Los plugins pueden comunicarse de forma estructurada sin depender de hooks internos ocultos o convenciones frágiles.
- Exposición controlada de funcionalidad: Puedes definir exactamente qué funcionalidades exponer y a quién, con esquemas claramente documentados y validación automática.
- Discoverability: Las herramientas externas pueden explorar las capacidades disponibles en tu sitio de forma programática y tomar decisiones inteligentes.
Por Qué Importa el Abilities API
Si trabajas con herramientas modernas, el Abilities API es crucial:
- Agentes de IA: Claude, ChatGPT, o sistemas personalizados que necesiten entender qué pueden hacer en tu sitio
- Automatización sin código: n8n, Zapier, Make (Integromat) que requieren entender las capacidades disponibles
- Integración con aplicaciones externas: CRM, marketing automation, ERP, etc.
El Abilities API es el estándar moderno para comunicar capacidades de forma estructurada, segura y autodescubierta.
El Abilities API representa un paso importante en la evolución de WordPress hacia una plataforma más interoperable y preparada para el futuro. Proporciona una forma clara, estandarizada y segura para definir y descubrir funcionalidades.
Si tu sitio es WordPress 6.9 o superior y necesitas que herramientas externas (especialmente agentes de IA) interactúen con tu sitio de forma predecible, el Abilities API es la mejor práctica moderna.
A medida que más plugins y temas adopten esta API, podemos esperar un ecosistema WordPress más rico donde las capacidades sean fácilmente descubribles y utilizables en diferentes contextos.
