Ability Rest API Integration

[agibson-godaddy]

Summary

Adds optional automatic REST API endpoint generation for abilities that opt in via a new RestConfig data object. When an ability carries a non-null RestConfig, the framework automatically registers a WordPress REST API route that executes the ability through WP_Ability::execute(), letting WP core handle input/output validation, permission checks, and lifecycle hooks.

Story: MWC-19480

Release:

Details

New classes

• RestConfig — DTO on the Ability data object that declares how an ability should be exposed as a REST endpoint. Configures path, namespace prefix, version, HTTP method, and optional input/output adapter class-strings.
• AbilityRestRegistrar — Core class that bridges abilities to REST routes. Iterates the provider's abilities and calls register_rest_route() for each one with a RestConfig. Handles:
  • Namespace resolution: auto-derives from the ability name (e.g. woocommerce-memberships-for-teams/... → wc-memberships-for-teams/v1), or uses an explicit override.
  • HTTP method inference: readonly annotation → GET, destructive → DELETE, otherwise POST. Explicit $method on RestConfig takes precedence.
  • Input/output adapters: optional class-string references to RestInputAdapterContract / RestOutputAdapterContract implementations that transform request data before execution and result data before response.
  • Default serialization: JsonSerializable objects and arrays of them are serialized automatically when no output adapter is provided.
  • Schema propagation: builds WP REST arg definitions from the ability's JSON Schema inputSchema and exposes outputSchema as the route's response schema.
• RestInputAdapterContract / RestOutputAdapterContract — Contracts for adapter classes.

Modified classes

• Ability — Added nullable $restConfig property (last constructor param, backwards compatible).
• AbilitiesHandler — Hooks rest_api_init inside the canUseAbilitiesApi() guard to register REST routes.
• AbstractAbilitiesProvider — Caches getAbilities() result so it's only built once (both abilities init and REST init consume it).

QA

• QA in https://github.com/gdcorp-partners/woocommerce-memberships-for-teams/pull/13 passes

Before merge

• I have confirmed these changes in each supported minor WooCommerce version

[Copilot]

Pull request overview

Adds optional automatic WordPress REST API route registration for Abilities that opt in via a new RestConfig DTO, including optional input/output adapters and schema propagation.

Changes:

• Introduces RestConfig, REST adapter contracts, and AbilityRestRegistrar to auto-register REST routes for configured abilities.
• Hooks REST registration into rest_api_init and caches provider abilities to avoid rebuilding for multiple init phases.
• Adds unit tests for REST registrar/config plus a WP_Error unit-test stub and documentation updates.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
woocommerce/Abilities/Rest/AbilityRestRegistrar.php	New registrar that maps opt-in abilities to register_rest_route() endpoints with adapters + schema plumbing.
woocommerce/Abilities/DataObjects/RestConfig.php	New DTO describing REST exposure (namespace/version/path/method + adapters).
woocommerce/Abilities/DataObjects/Ability.php	Adds nullable restConfig to the Ability DTO (constructor + property).
woocommerce/Abilities/Contracts/RestInputAdapterContract.php	New contract for request-to-ability input adaptation.
woocommerce/Abilities/Contracts/RestOutputAdapterContract.php	New contract for ability-result-to-response adaptation.
woocommerce/Abilities/AbstractAbilitiesProvider.php	Caches resolved abilities so they’re built once and reused across init hooks.
woocommerce/Abilities/AbilitiesHandler.php	Adds rest_api_init hook to invoke the new registrar (under the existing abilities API guard).
tests/unit/Abilities/Rest/AbilityRestRegistrarTest.php	Unit coverage for registrar behaviors (namespace/method inference, adapters, args/schema, callback flow).
tests/unit/Abilities/DataObjects/RestConfigTest.php	Unit coverage for RestConfig defaults and full construction.
tests/unit/Abilities/AbilitiesHandlerTest.php	Updates hook expectations to include rest_api_init.
tests/bootstrap.php	Loads a WP_Error stub when WP core isn’t available under WP_Mock.
tests/Stubs/WP_Error.php	Minimal WP_Error stub to support unit tests.
.agents/guides/ABILITIES-IMPLEMENTATION-GUIDE.md	Documents optional REST endpoint configuration and adapter patterns.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

This test uses a route path without a leading slash ('teams'), while RestConfig’s docs/tests and the guide examples show paths like '/teams'. Pick one convention and use it consistently; if the intent is WordPress’ typical register_rest_route() usage, update this to include the leading / to match RestConfigTest and avoid confusion.