Changeset 61032 for trunk/src/wp-includes/rest-api.php

Timestamp:

10/21/2025 01:50:11 PM (5 months ago)

Author:

gziolo

Message:

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.

File:

• trunk/src/wp-includes/rest-api.php (modified) (1 diff)

trunk/src/wp-includes/rest-api.php

@@ -484 +484 @@
     $font_collections_controller = new WP_REST_Font_Collections_Controller();
     $font_collections_controller->register_routes();
+
+    // Abilities.
+    $abilities_run_controller  = new WP_REST_Abilities_V1_Run_Controller();
+    $abilities_run_controller->register_routes();
+    $abilities_list_controller = new WP_REST_Abilities_V1_List_Controller();
+    $abilities_list_controller->register_routes();
 }