Add REST API controllers for Abilities API by emdashcodes · Pull Request #6 · WordPress/abilities-api

emdashcodes · 2025-08-12T15:48:32Z

Closes #2.

This PR adds initial REST API endpoints to the Abilities API with support for both resource (GET) and tool (POST) type abilities.

How

Implements the following REST API endpoints:

WP_REST_Abilities_List_Controller - Handles listing abilities and retrieving individual abilities
- GET /wp-json/wp/v2/abilities - List all registered abilities
- GET /wp-json/wp/v2/abilities/{id} - Get a specific ability by ID
WP_REST_Abilities_Run_Controller - Handles executing abilities
- GET/POST /wp-json/wp/v2/abilities/{id}/run - Execute an ability (method depends on ability type)
  - Resources use GET
  - Tools use POST

Testing Steps

Make sure all unit tests pass

If you enable the Ability API as a plugin:

Test listing abilities: GET /wp/v2/abilities
Test getting a specific ability: GET /wp/v2/abilities/{id}
Test executing a resource ability: GET /wp/v2/abilities/{id}/run
Test executing a tool ability: POST /wp/v2/abilities/{id}/run

abilities-api.php

gziolo · 2025-08-13T05:02:39Z

I landed #3, which triggered GitHub automations, and accidentally closed this PR after the target branch got deleted 😅

I'll try to fix it.

gziolo · 2025-08-13T05:04:18Z

Reopened and changed the base branch, but it will require a rebase to remove my commits from the list of changes.

abilities-api.php

src/rest/class-wp-rest-abilities-list-controller.php

src/rest/class-wp-rest-abilities-init.php

src/rest/class-wp-rest-abilities-list-controller.php

tests/unit/REST/WPRESTAbilitiesListControllerTest.php

gziolo

I reviewed all the code and tests for the list controller and left my feedback inline. I still need to check the run controller. Everything is looking great, my feedback is mostly about minor things or I had some questions/notes where I wasn't entirely sure how it works.

My only high-level, important feedback is around using a single form: id or name to uniquely identify the ability.

Copilot

Pull Request Overview

This PR implements REST API controllers for the Abilities API, enabling web-based access to both resource and tool type abilities through standardized endpoints.

Key Changes:

Added two REST API controllers (WP_REST_Abilities_List_Controller and WP_REST_Abilities_Run_Controller) with full test coverage
Implemented HTTP method validation where resource abilities use GET and tool abilities use POST
Added comprehensive validation for input/output schemas and permission checks

Reviewed Changes

Copilot reviewed 16 out of 18 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`src/rest/class-wp-rest-abilities-list-controller.php`	Implements endpoints for listing and retrieving individual abilities
`src/rest/class-wp-rest-abilities-run-controller.php`	Handles ability execution with method validation and comprehensive error handling
`src/rest/class-wp-rest-abilities-init.php`	Initializes and registers REST API routes on the `rest_api_init` hook
`tests/unit/REST/WPRESTAbilitiesListControllerTest.php`	Comprehensive test coverage for list controller including pagination and permissions
`tests/unit/REST/WPRESTAbilitiesRunControllerTest.php`	Extensive test coverage for run controller including method validation and error handling
Various test and configuration files	Supporting infrastructure for unit testing and development

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

src/rest/class-wp-rest-abilities-run-controller.php

Fixed REST controller calling non-existent get_execute_callback() method. Always show run link for abilities in REST responses.

- Register run controller before list controller to fix route precedence - Support both GET (resources) and POST (tools) methods based on ability type - Add TODO comment explaining load order issue with ALLMETHODS - Remove result wrapper to match Feature API response format - Handle query params for GET requests and JSON body for POST

codecov · 2025-08-13T14:52:16Z

Codecov Report

❌ Patch coverage is 91.10429% with 29 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (trunk@c40f122). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
...rc/rest/class-wp-rest-abilities-run-controller.php	81.57%	28 Missing ⚠️
abilities-api.php	0.00%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff            @@
##             trunk       #6   +/-   ##
========================================
  Coverage         ?   90.32%           
  Complexity       ?      103           
========================================
  Files            ?        7           
  Lines            ?      558           
  Branches         ?        0           
========================================
  Hits             ?      504           
  Misses           ?       54           
  Partials         ?        0

Flag	Coverage Δ
unit	`90.32% <91.10%> (?)`

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

PHPStan fixes: - Add return type annotations for void methods - Add array type hints for array parameters and returns - Cast integer header values to strings (PHPStan stubs expect strings) - Add ignore rule for WP_REST_Request generic types with explanation PHPCS compliance: - Add file documentation headers to all REST API files - Use fully qualified class names in PHPDoc comments - Add 'abilities-api' domain to all translation functions - Fix array alignment and spacing issues - Fix short ternary operators to explicit conditionals - Add periods to inline comments - Simplify elseif logic in run controller Type hints and modern PHP: - Add native PHP type hints where compatible with PHP 7.4+ - Add WP_REST_Abilities prefix to allowed prefixes in PHPCS config - Use native return types (void, array, bool) and parameter types

…t REST API

- Add array<string, mixed> type hint for get_input_from_request return - Add public visibility to DEFAULT_PER_PAGE constant

phpstan.neon.dist

emdashcodes · 2025-08-13T19:47:09Z

I've addressed the static analysis and PHPCS issues from this branch. The remaining ones seem to be on trunk.

src/rest/class-wp-rest-abilities-list-controller.php

@return

- Add test coverage for REST API controllers (List, Run, Init) - Add tests for uncovered lines in run controller (29 lines) - Add tests for init class route registration - Add malformed input tests for edge cases - Remove PHP type hints from REST controllers for WordPress compatibility - Fix test expectations to match WordPress REST API behavior - Use PHPUnit data providers for better test organization - Fix HTTP method validation tests - Add missing @return documentation tag Test coverage improvements: - WPRESTAbilitiesRunControllerTest: Full coverage with input validation, permissions, HTTP methods - WPRESTAbilitiesListControllerTest: Pagination, special characters, invalid parameters - WPRESTAbilitiesInitTest: Route registration and controller instantiation All tests passing (105 tests, 246 assertions)

- WordPress core's WP_REST_Controller doesn't have type hints on methods - Adding type hints causes fatal errors due to signature mismatch - Exclude Squiz.Commenting.FunctionComment.TypeHintMissing for REST controllers - Also exclude Slevomat type hint rules for consistency - This is a common WordPress compatibility issue

justlevine · 2025-08-13T20:57:45Z

src/rest/class-wp-rest-abilities-list-controller.php

+	 * @return \WP_REST_Response|\WP_Error Response object on success, or WP_Error object on failure.
+	 */
+	public function get_item( $request ) {
+		$ability = wp_get_ability( $request['name'] );


Is there a reason not to use WP_REST_Request->get_param() (/ ->get_params() elsewhere )?

We lose the rest_request_parameter_order filter by relying on \ArrayAccess

I see both forms used in REST API controllers included in WP core, sometimes even in the same handler 😅

@gziolo I think that's a sign of tech debt, not an endorsement of pattern 😅

We can update to use get_param() 👍🏻

Will you take care of it?

phpcs.xml.dist

gziolo

Thank you for rebasing with trunk and addressing all feedback. I see the increased unit tests coverage added in 9b071cb 👏🏻

Let's land it in the current shape and address the code quality configuration challenges seperately. I also plan to open follow-up issues for TODO items included in the codebase.

emdashcodes marked this pull request as draft August 12, 2025 15:48

emdashcodes changed the title ~~Add REST API controllers for Abilities API~~ [WIP] Add REST API controllers for Abilities API Aug 12, 2025

gziolo assigned emdashcodes Aug 12, 2025

gziolo added the [Type] Task Issues or PRs that have been broken down into an individual action to take label Aug 12, 2025

emdashcodes changed the title ~~[WIP] Add REST API controllers for Abilities API~~ Add REST API controllers for Abilities API Aug 13, 2025

emdashcodes marked this pull request as ready for review August 13, 2025 02:28

emdashcodes mentioned this pull request Aug 13, 2025

Add Abilities API bridge for WP Feature API Automattic/wp-feature-api#90

Closed

emdashcodes commented Aug 13, 2025

View reviewed changes

abilities-api.php Outdated Show resolved Hide resolved

gziolo mentioned this pull request Aug 13, 2025

Implement server-side registry for Abilities API #3

Merged

gziolo self-requested a review August 13, 2025 04:48

gziolo deleted the branch WordPress:trunk August 13, 2025 04:58

gziolo closed this Aug 13, 2025

gziolo reopened this Aug 13, 2025

gziolo changed the base branch from add/server-side-registry to trunk August 13, 2025 05:02