Docs: REST API Reference

docs/5.rest-api.md

@@ -0,0 +1,197 @@
+# 5. REST API Reference
+
+The WordPress Abilities API provides REST endpoints that allow external systems to discover and execute abilities via HTTP requests.
+
+## Schema
+
+The Abilities API endpoints are available under the `/wp/v2/abilities` namespace.
+
+### Ability Object
+
+Abilities are represented in JSON with the following structure:
+
+```json
+{
+  "name": "my-plugin/get-site-info",
+  "label": "Get Site Information",
+  "description": "Retrieves basic information about the WordPress site",
+  "input_schema": {
+    "type": "object",
+    "properties": {},
+    "additionalProperties": false
+  },
+  "output_schema": {
+    "type": "object",
+    "properties": {
+      "name": {"type": "string"},
+      "url": {"type": "string", "format": "uri"}
+    }
+  },
+  "meta": {}
+}
+```
+
+## List Abilities
+
+### Definition
+
+`GET /wp/v2/abilities`
+
+### Arguments
+
+- `page` *(integer)*: Current page of the collection. Default: `1`
+- `per_page` *(integer)*: Maximum number of items to return per page. Default: `50`, Maximum: `100`
+
+### Example Request
+
+```bash
+curl https://example.com/wp-json/wp/v2/abilities
+```
+
+### Example Response
+
+```json
+[
+  {
+    "name": "my-plugin/get-site-info",
+    "label": "Get Site Information",
+    "description": "Retrieves basic information about the WordPress site",
+    "input_schema": {
+      "type": "object",
+      "properties": {},
+      "additionalProperties": false
+    },
+    "output_schema": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Site name"
+        }
+      }
+    },
+    "meta": {}
+  }
+]
+```
+
+## Retrieve an Ability
+
+### Definition
+
+`GET /wp/v2/abilities/(?P<namespace>[a-z0-9-]+)/(?P<ability>[a-z0-9-]+)`
+
+### Arguments
+
+- `namespace` *(string)*: The namespace part of the ability name
+- `ability` *(string)*: The ability name part
+
+### Example Request
+
+```bash
+curl https://example.com/wp-json/wp/v2/abilities/my-plugin/get-site-info
+```
+
+### Example Response
+
+```json
+{
+  "name": "my-plugin/get-site-info",
+  "label": "Get Site Information",
+  "description": "Retrieves basic information about the WordPress site",
+  "input_schema": {
+    "type": "object",
+    "properties": {},
+    "additionalProperties": false
+  },
+  "output_schema": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "type": "string",
+        "description": "Site name"
+      },
+      "url": {
+        "type": "string",
+        "format": "uri",
+        "description": "Site URL"
+      }
+    }
+  },
+  "meta": {
+    "category": "site-info"
+  }
+}
+```
+
+## Execute an Ability
+
+### Definition
+
+`POST /wp/v2/abilities/(?P<namespace>[a-z0-9-]+)/(?P<ability>[a-z0-9-]+)/run`
+
+### Arguments
+
+- `namespace` *(string)*: The namespace part of the ability name
+- `ability` *(string)*: The ability name part
+- `input` *(object)*: Input data for the ability as defined by its input schema
+
+### Example Request (No Input)
+
+```bash
+curl -X POST https://example.com/wp-json/wp/v2/abilities/my-plugin/get-site-info/run
+```
+
+### Example Request (With Input)
+
+```bash
+curl -X POST \
+  -H "Content-Type: application/json" \
+  -d '{"input":{"option_name":"blogname","option_value":"New Site Name"}}' \
+  https://example.com/wp-json/wp/v2/abilities/my-plugin/update-option/run
+```
+
+### Example Response (Success)
+
+```json
+{
+  "name": "My WordPress Site",
+  "url": "https://example.com"
+}
+```
+
+### Example Response (Error)
+
+```json
+{
+  "code": "ability_invalid_permissions",
+  "message": "Ability \"my-plugin/update-option\" does not have necessary permission.",
+  "data": {
+    "status": 403
+  }
+}
+```
+
+## Authentication
+
+The Abilities API supports all WordPress REST API authentication methods:
+
+- Cookie authentication (same-origin requests)
+- Application passwords (recommended for external access)
+- Custom authentication plugins
+
+### Using Application Passwords
+
+```bash
+curl -H "Authorization: Bearer YOUR_APP_PASSWORD" \
+  https://example.com/wp-json/wp/v2/abilities
+```
+
+## Error Responses
+
+The API returns standard WordPress REST API error responses with these common codes:
+
+- `ability_not_found` - The specified ability is not registered
+- `ability_invalid_input` - Input validation failed according to the ability's schema
+- `ability_invalid_permissions` - Current user lacks permission to execute the ability
+- `ability_execution_failed` - The ability callback returned a WP_Error