Docs: REST API Reference

[gziolo]

Closes #28.

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

Covers three routes available:

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

This is a first pass generated and iterated with Claude Code.

[Copilot]

Pull Request Overview

This PR adds comprehensive REST API documentation for the WordPress Abilities API, documenting how external systems can discover and execute abilities via HTTP requests. The documentation covers the three main endpoints for interacting with abilities: listing all abilities, retrieving a specific ability, and executing an ability.

• Documents the REST API schema and ability object structure
• Provides detailed endpoint definitions with examples for GET and POST requests
• Includes authentication methods and error response documentation

---

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.33%. Comparing base (94d950a) to head (c0ffb6c).
⚠️ Report is 1 commits behind head on trunk.

Additional details and impacted files

@@            Coverage Diff            @@
##              trunk      #77   +/-   ##
=========================================
  Coverage     83.33%   83.33%           
  Complexity       96       96           
=========================================
  Files             8        8           
  Lines           516      516           
=========================================
  Hits            430      430           
  Misses           86       86           

Flag	Coverage Δ
unit	83.33% <ø> (ø)

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.

[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: jonathanbossenger <[email protected]>

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

[jonathanbossenger]

@gziolo quick question, from my local testing it appears that all Abilities API REST Endpoints require authentication, is this correct? Want to make sure of my facts before adding review comments.

[gziolo]

quick question, from my local testing it appears that all Abilities API REST Endpoints require authentication, is this correct? Want to make sure of my facts before adding review comments.

I had to double-check, but the answer is:

• to get all abilities or a single ability current_user_can( 'read' ) check is performed, so the user needs to be authorized
• to run an ability, it all depends on the ability itself and what permission it defined

@johnbillion, any thoughts about the current approach to permissions when calling the REST API endpoints?

[jonathanbossenger]

One minor suggestion, but otherwise it all looks good, and checks out.