Add new show_in_rest arg to control REST API exposure

[gziolo]

Noted in #83.

Introduces show_in_rest arg in the server-side registry in the case devs don't want their abilities to be discoverable in REST API endpoints. By default, abilities won't get exposed which aligns with many other fundamental pieces in WordPress like post types, taxonomies, meta, etc.

It also adds a new method on WP_Ability object show_in_rest() to allow checking whether the ability should be exposed through REST API.

Example

// Ability that does not show in REST.
$ability = wp_register_ability(
	'test/not-show-in-rest',
	array(
		'label'               => 'Hidden from REST',
		'description'         => 'It does not show in REST.',
		'execute_callback'    => static function (): int {
			return 0;
		},
		'permission_callback' => '__return_true',
	)
);
// false === $ability->show_in_rest() 


// Ability that shows in REST.
$ability = wp_register_ability(
	'test/show-in-rest',
	array(
		'label'               => 'Show in REST',
		'description'         => 'It shows in REST.',
		'execute_callback'    => static function (): int {
			return 0;
		},
		'permission_callback' => '__return_true',
		'show_in_rest' => true,
	)
);
// true === $ability->show_in_rest() 

Testing

Run npm run test:php to execute extended test coverage for the new functionality.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.17%. Comparing base (a9039a3) to head (31bd9f5).
⚠️ Report is 1 commits behind head on trunk.

Additional details and impacted files

@@             Coverage Diff              @@
##              trunk     #103      +/-   ##
============================================
+ Coverage     85.98%   86.17%   +0.19%     
- Complexity      105      110       +5     
============================================
  Files            16       16              
  Lines           792      803      +11     
  Branches         85       86       +1     
============================================
+ Hits            681      692      +11     
  Misses          111      111              

Flag	Coverage Δ
javascript	92.62% <ø> (ø)
unit	83.78% <100.00%> (+0.31%)	⬆️

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.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Copilot]

Pull Request Overview

This PR adds a new show_in_rest argument to the abilities API that controls whether an ability is exposed through the REST API endpoints. When set to false (the default), abilities are hidden from REST API listing and individual endpoint access.

• Adds show_in_rest boolean property to the WP_Ability class with validation
• Updates REST API controllers to filter out abilities where show_in_rest is false
• Adds comprehensive test coverage for the new functionality

Reviewed Changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
includes/abilities-api/class-wp-ability.php	Adds show_in_rest property and has_show_in_rest() method with validation
includes/rest-api/endpoints/class-wp-rest-abilities-list-controller.php	Filters abilities list and individual ability access based on show_in_rest
includes/rest-api/endpoints/class-wp-rest-abilities-run-controller.php	Prevents execution of abilities not shown in REST
includes/abilities-api/class-wp-abilities-registry.php	Updates documentation to include show_in_rest parameter
includes/abilities-api.php	Updates function documentation for wp_register_ability
tests/unit/abilities-api/wpAbility.php	Tests default behavior and explicit setting of show_in_rest
tests/unit/abilities-api/wpAbilitiesRegistry.php	Tests validation of invalid show_in_rest values
tests/unit/abilities-api/wpRegisterAbility.php	Updates test to verify show_in_rest property handling
tests/unit/rest-api/wpRestAbilitiesListController.php	Tests filtering and 404 responses for hidden abilities
tests/unit/rest-api/wpRestAbilitiesRunController.php	Tests execution blocking for hidden abilities

---

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

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: gziolo <[email protected]>
Co-authored-by: JasonTheAdams <[email protected]>
Co-authored-by: justlevine <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[JasonTheAdams]

Nice addition, @gziolo! One very minor suggestion.

[justlevine]

@gziolo what if we relocated this to our first official "meta" property: $meta['show_in_rest']?

This would allow us to drop the extra property + public getter + usage in favor of the existing $ability->get_meta( 'show_in_rest' ), keeping the api the same size while still supporting the same functionality. It also scales better for both known and unknown future requirements (e.g. show_in_mcp, acp and whatever else), and makes more sense from a semantic perspective (and therefore DX).

[JasonTheAdams]

Good work! LGTM!

[JasonTheAdams]

I didn't see @justlevine's comment when I approved. Do we have a clear definition of what does and does not belong in meta?

[gziolo]

@emdashcodes suggested in #38 (comment) that show_in_rest defaults to true. That’s the behavior before this PR, and since it’s a brand new concept I’m open to going with true. What other people think about it?

As for using meta, we didn’t arrive to conclusions but my thinking is it’s primarily for extenders to put additional details they need. When I put show_in_rest as top-level property I mirrored other concepts (post types, taxonomies, meta, options), but I don’t feel strongly about it. One thing important to keep in mind is we need a default value here and have it explicitly documented.

[justlevine]

@emdashcodes suggested in #38 (comment) that show_in_rest defaults to true. That’s the behavior before this PR, and since it’s a brand new concept I’m open to going with true. What other people think about it?

I'm good either way. Long term it's probably going to get inferred from a public: bool prop anyway, and since as long as permission_callback is for all intents and purposes required, there's not too much risk to defaulting to true

[gziolo]

Based on the comment from @JasonTheAdams in #106 (comment), I will land this PR as is. However, I will immediately start working on a follow-up scoped to the following:

• Move show_in_rest to meta.show_in_rest.
• Update the default value to true as a separate commit, in case we decide to stay with false.

[emdashcodes]

Thanks @gziolo! I feel pretty strongly that we should default to true for the same argument that we're making categories required. If it's set to false, most people aren't going to read the documentation and enable it, and a lot of these won't automatically be discoverable by the client.

Having these opted-in by default allows for a lot of cool things like the command palette and automatically discovering them on the client and passing them to a client agent for example, and it would be nice if most of these were enabled "by default".

[justlevine]

Having these opted-in by default allows for a lot of cool things like the command palette

(My hunch is this too will more likely be encapsulated by a show_in_cp prop that also inherited from an eventual public: bool )

[gziolo]

I have a follow-up ready for review based on my previous comment #103 (comment):

• Move show_in_rest to meta in the registration process #107

[gziolo]

Regarding Command Palette, the plan is to introduce the Workflows concept as a facade for consuming Abilities. The point still holds that abilities need to be exposed on the client in the first place 👍🏻