gziolo
7aa1b7ef5b
Abilities API: Normalize input from schema
...
Without this patch REST API would require a weird empty `?input` field for optional input given how the current controller works with input schema when it defines the expected shape. This patch normalizes the input for the ability, applying the default value from the input schema when needed.
Developed in https://github.com/WordPress/wordpress-develop/pull/10395 .
Follow-up [61032], [61045].
Props gziolo, jorgefilipecosta, mukesh27.
Fixes #64139 .
Built from https://develop.svn.wordpress.org/trunk@61047
git-svn-id: http://core.svn.wordpress.org/trunk@60383 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2025-10-22 15:04:30 +00:00
gziolo
d3fe16afc4
Abilities API: Introduce server-side registry and REST API endpoints
...
Feature proposal at https://make.wordpress.org/ai/2025/07/17/abilities-api/ .
Project developed in https://github.com/WordPress/abilities-api .
Introduces a new Abilities API that allows WordPress plugins and themes to register and execute custom abilities with built-in permission checking, input/output validation via JSON Schema, and REST API integration.
## Public Functions
### Ability Management
- `wp_register_ability( string $name, array $args ): ?WP_Ability` - Registers a new ability (must be called on `wp_abilities_api_init` hook)
- `wp_unregister_ability( string $name ): ?WP_Ability` - Unregisters an ability
- `wp_has_ability( string $name ): bool` - Checks if an ability is registered
- `wp_get_ability( string $name ): ?WP_Ability` - Retrieves a registered ability
- `wp_get_abilities(): array` - Retrieves all registered abilities
### Ability Category Management
- `wp_register_ability_category( string $slug, array $args ): ?WP_Ability_Category` - Registers an ability category (must be called on `wp_abilities_api_categories_init` hook)
- `wp_unregister_ability_category( string $slug ): ?WP_Ability_Category` - Unregisters an ability category
- `wp_has_ability_category( string $slug ): bool` - Checks if an ability category is registered
- `wp_get_ability_category( string $slug ): ?WP_Ability_Category` - Retrieves a registered ability category
- `wp_get_ability_categories(): array` - Retrieves all registered ability categories
## Public Classes
- `WP_Ability` - Encapsulates ability properties and methods (execute, check_permission, validate_input, etc.)
- `WP_Ability_Category` - Encapsulates ability category properties
- `WP_Abilities_Registry` - Manages ability registration and lookup (private, accessed via functions)
- `WP_Ability_Categories_Registry` - Manages ability category registration (private, accessed via functions)
- `WP_REST_Abilities_V1_List_Controller` - REST controller for listing abilities
- `WP_REST_Abilities_V1_Run_Controller` - REST controller for executing abilities
## REST API Endpoints
### Namespace: `wp-abilities/v1`
#### List Abilities
- `GET /wp-abilities/v1/abilities` - Retrieve all registered abilities
- Query parameters: `page`, `per_page`, `category`
#### Get Single Ability
- `GET /wp-abilities/v1/abilities/(?P<name>[a-zA-Z0-9\-\/]+)` - Retrieve a specific ability by name
#### Execute Ability
- `GET|POST|DELETE /wp-abilities/v1/abilities/(?P<name>[a-zA-Z0-9\-\/]+)/run` - Execute an ability
- Supports multiple HTTP methods based on ability annotations
- Validates input against ability's input schema
- Validates output against ability's output schema
- Performs permission checks via ability's permission callback
## Hooks
### Actions
- `wp_abilities_api_categories_init` - Fired when ability categories registry is initialized (register categories here)
- `wp_abilities_api_init` - Fired when abilities registry is initialized (register abilities here)
- `wp_before_execute_ability` - Fired before an ability gets executed, after input validation and permissions check
- `wp_after_execute_ability` - Fires immediately after an ability finished executing
### Filters
- `wp_register_ability_category_args` - Filters ability category arguments before registration
- `wp_register_ability_args` - Filters ability arguments before registration
Developed in https://github.com/WordPress/wordpress-develop/pull/9410 .
Props gziolo, jorbin, justlevine, westonruter, jason_the_adams, flixos90, karmatosed, timothyblynjacobs.
Fixes #64098 .
Built from https://develop.svn.wordpress.org/trunk@61032
git-svn-id: http://core.svn.wordpress.org/trunk@60368 1a063a9b-81f0-0310-95a4-ce76da25c4cd
2025-10-21 13:52:27 +00:00
