Document REST API usage

[jonathanbossenger]

Document the available REST API endpoints and how to use them for registered abilities.

[jonathanbossenger]

@gziolo please feel to add any other specific items you'd like to see in the docs for the REST API.

[gziolo]

We have three routes available:

• fetching all abilities
• fetching a single ability
• executing a single ability

Routes are defined here:

abilities-api/includes/rest-api/endpoints/class-wp-rest-abilities-list-controller.php

Lines 52 to 84 in 32dfc3a

	register_rest_route(
	$this->namespace,
	'/' . $this->rest_base,
	array(
	array(
	'methods' => WP_REST_Server::READABLE,
	'callback' => array( $this, 'get_items' ),
	'permission_callback' => array( $this, 'get_permissions_check' ),
	'args' => $this->get_collection_params(),
	),
	'schema' => array( $this, 'get_public_item_schema' ),
	)
	);
	register_rest_route(
	$this->namespace,
	'/' . $this->rest_base . '/(?P<name>[a-zA-Z0-9\-\/]+)',
	array(
	'args' => array(
	'name' => array(
	'description' => __( 'Unique identifier for the ability.' ),
	'type' => 'string',
	'pattern' => '^[a-zA-Z0-9\-\/]+$',
	),
	),
	array(
	'methods' => WP_REST_Server::READABLE,
	'callback' => array( $this, 'get_item' ),
	'permission_callback' => array( $this, 'get_permissions_check' ),
	),
	'schema' => array( $this, 'get_public_item_schema' ),
	)
	);

abilities-api/includes/rest-api/endpoints/class-wp-rest-abilities-run-controller.php

Lines 44 to 70 in 32dfc3a

	register_rest_route(
	$this->namespace,
	'/' . $this->rest_base . '/(?P<name>[a-zA-Z0-9\-\/]+?)/run',
	array(
	'args' => array(
	'name' => array(
	'description' => __( 'Unique identifier for the ability.' ),
	'type' => 'string',
	'pattern' => '^[a-zA-Z0-9\-\/]+$',
	),
	),
	// TODO: We register ALLMETHODS because at route registration time, we don't know
	// which abilities exist or their types (resource vs tool). This is due to WordPress
	// load order - routes are registered early, before plugins have registered their abilities.
	// This approach works but could be improved with lazy route registration or a different
	// architecture that allows type-specific routes after abilities are registered.
	// This was the same issue that we ended up seeing with the Feature API.
	array(
	'methods' => WP_REST_Server::ALLMETHODS,
	'callback' => array( $this, 'run_ability_with_method_check' ),
	'permission_callback' => array( $this, 'run_ability_permissions_check' ),
	'args' => $this->get_run_args(),
	),
	'schema' => array( $this, 'get_run_schema' ),
	)
	);

It should be largely compatible with some tweaks to the WP Feature API as explored by @emdashcodes in Automattic/wp-feature-api#90. In effect, some parts of https://github.com/Automattic/wp-feature-api/blob/trunk/docs/5.rest-api-endpoints.md could get used as a starting point.

[jonathanbossenger]

Thanks. Will see if I can get some time to work on this in the coming week.