REST API 端点

查看官方原文 ↗

💡 云策文档标注

概述

WordPress Abilities API 提供 REST 端点，允许外部系统通过 HTTP 请求发现和执行能力。文档详细介绍了端点访问控制、数据结构、列表和操作能力的方法。

关键要点

所有 Abilities REST API 端点需要认证用户访问，执行权限由 Ability 的 permission_callback() 控制。
通过注册能力时设置 show_in_rest 元数据控制 REST API 暴露，默认不暴露。
端点位于 /wp-abilities/v1 命名空间下，支持列出能力、分类、检索和执行能力。
能力执行使用 /run 端点，HTTP 方法根据能力的只读、破坏性等注释决定。
支持多种认证方式，包括应用密码，并定义了常见错误响应代码。

代码示例

// 注册能力时控制 REST API 暴露
register_ability([
    'name' => 'wporg/get-site-info',
    'show_in_rest' => true, // 暴露到 REST API
    // 其他参数...
]);

// 列出能力的示例请求
curl https://example.com/wp-json/wp-abilities/v1/abilities

// 执行能力（GET 请求，带输入）
curl "https://example.com/wp-json/wp-abilities/v1/my-plugin/get-user-info/run?input=%7B%22user_id%22%3A1%7D"

// 执行能力（POST 请求，带 JSON 输入）
curl -X POST 
  -H "Content-Type: application/json" 
  -d '{"input":{"option_name":"blogname","option_value":"New Site Name"}}' 
  https://example.com/wp-json/wp-abilities/v1/my-plugin/update-option/run

注意事项

show_in_rest 设置为 false 的能力在 REST API 中隐藏，通过 REST 端点访问会返回 rest_ability_not_found 错误。
执行能力时需根据能力注释选择正确的 HTTP 方法（GET、POST 或 DELETE），以确保操作安全。
输入数据需符合能力定义的 input_schema，否则会返回错误如 ability_invalid_input。

📄 原文内容

The WordPress Abilities API provides REST endpoints that allow external systems to discover and execute abilities via HTTP requests.

User access

Access to all Abilities REST API endpoints requires an authenticated user (see the Authentication section). Access to execute individual Abilities is restricted based on the permission_callback() of the Ability.

Controlling REST API Exposure

By default, registered abilities are not exposed via the REST API. You can control whether an individual ability appears in the REST API by using the show_in_rest meta when registering the ability:

show_in_rest => true: The ability is listed in REST API responses and can be executed via REST endpoints.
show_in_rest => false (default): The ability is hidden from REST API listings and cannot be executed via REST endpoints. The ability remains available for internal PHP usage via wp_get_ability() and $ability->execute().

Abilities with meta show_in_rest => false will return a rest_ability_not_found error if accessed via REST endpoints.

Schema

The Abilities API endpoints are available under the /wp-abilities/v1 namespace.

Ability Object

Abilities are represented in JSON with the following structure:

{
  "name": "wporg/get-site-info",
  "label": "Get Site Information",
  "description": "Retrieves basic information about the WordPress site.",
  "category": "site-information",
  "output_schema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string",
        "description": "Site name"
      },
      "url": {
        "type": "string",
        "format": "uri",
        "description": "Site URL"
      }
    }
  },
  "meta": {
    "annotations": {
      "instructions": "",
      "readonly": true,
      "destructive": false,
      "idempotent": false
    }
  }
}

List Abilities

Definition

GET /wp-abilities/v1/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.
category (string): Filter abilities by category slug.

Example Request

curl https://example.com/wp-json/wp-abilities/v1/abilities

Example Response

[
  {
    "name": "wporg/get-site-info",
    "label": "Get Site Information",
    "description": "Retrieves basic information about the WordPress site.",
    "category": "site-information",
    "output_schema": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Site name"
        },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "Site URL"
        }
      }
    },
    "meta": {
      "annotations": {
        "instructions": "",
        "readonly": false,
        "destructive": true,
        "idempotent": false
      }
    }
  }
]

List Categories

Definition

GET /wp-abilities/v1/categories

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

curl -u 'USERNAME:APPLICATION_PASSWORD' 
  https://example.com/wp-json/wp-abilities/v1/categories

Example Response

[
  {
    "slug": "data-retrieval",
    "label": "Data Retrieval",
    "description": "Abilities that retrieve and return data from the WordPress site.",
    "meta": {},
    "_links": {
      "self": [
        {
          "href": "https://example.com/wp-json/wp-abilities/v1/categories/data-retrieval"
        }
      ],
      "collection": [
        {
          "href": "https://example.com/wp-json/wp-abilities/v1/categories"
        }
      ],
      "abilities": [
        {
          "href": "https://example.com/wp-json/wp-abilities/v1/?category=data-retrieval"
        }
      ]
    }
  }
]

Retrieve a Category

Definition

GET /wp-abilities/v1/categories/{slug}

Arguments

slug (string): The unique slug of the category.

Example Request

curl -u 'USERNAME:APPLICATION_PASSWORD' 
  https://example.com/wp-json/wp-abilities/v1/categories/data-retrieval

Example Response

{
  "slug": "data-retrieval",
  "label": "Data Retrieval",
  "description": "Abilities that retrieve and return data from the WordPress site.",
  "meta": {},
  "_links": {
    "self": [
      {
        "href": "https://example.com/wp-json/wp-abilities/v1/categories/data-retrieval"
      }
    ],
    "collection": [
      {
        "href": "https://example.com/wp-json/wp-abilities/v1/categories"
      }
    ],
    "abilities": [
      {
        "href": "https://example.com/wp-json/wp-abilities/v1?category=data-retrieval"
      }
    ]
  }
}

Retrieve an Ability

Definition

GET /wp-abilities/v1/(?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

curl https://example.com/wp-json/wp-abilities/v1/my-plugin/get-site-info

Example Response

{
  "name": "wporg/get-site-info",
  "label": "Get Site Information",
  "description": "Retrieves basic information about the WordPress site.",
  "category": "site-information",
  "output_schema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string",
        "description": "Site name"
      },
      "url": {
        "type": "string",
        "format": "uri",
        "description": "Site URL"
      }
    }
  },
  "meta": {
    "annotations": {
      "instructions": "",
      "readonly": true,
      "destructive": false,
      "idempotent": false
    }
  }
}

Execute an Ability

Abilities are executed via the /run endpoint. The required HTTP method depends on the ability’s functionality and annotations:

Read-only abilities must use GET (readonly: true)
Regular abilities must use GET when they are readonly (readonly: true), and POST when they require an input (readonly: false)
Destructive abilities (destructive: true) must use DELETE

This distinction ensures read-only operations use safe HTTP methods that can be cached and don’t modify server state.

Definition

GET|POST|DELETE /wp-abilities/v1/(?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 (integer|number|boolean|string|array|object|null): Optional input data for the ability as defined by its input schema.
For GET and DELETE requests: pass as input query parameter (URL-encoded JSON)
For POST requests: pass in JSON body

Example Request (GET)

# No input
curl https://example.com/wp-json/wp-abilities/v1/my-plugin/get-site-info/run

# With input (URL-encoded)
curl "https://example.com/wp-json/wp-abilities/v1/my-plugin/get-user-info/run?input=%7B%22user_id%22%3A1%7D"

Example Request (POST)

# No input
curl -X POST https://example.com/wp-json/wp-abilities/v1/my-plugin/create-draft/run

# With input
curl -X POST 
  -H "Content-Type: application/json" 
  -d '{"input":{"option_name":"blogname","option_value":"New Site Name"}}' 
  https://example.com/wp-json/wp-abilities/v1/my-plugin/update-option/run

Example Request (DELETE)

# With input (URL-encoded)
curl -X DELETE "https://example.com/wp-json/wp-abilities/v1/my-plugin/delete-post/run?input=%7B%22post_id%22%3A123%7D"

Example Response (Success)

{
  "name": "My WordPress Site",
  "url": "https://example.com"
}

Example Response (Error)

{
  "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

curl -u 'USERNAME:APPLICATION_PASSWORD' 
  https://example.com/wp-json/wp-abilities/v1

Error Responses

The API returns standard WordPress REST API error responses with these common codes:

ability_missing_input_schema – the ability requires input but none was provided.
ability_invalid_input – input validation failed according to the ability’s schema.
ability_invalid_permissions – current user lacks permission to execute the ability.
ability_invalid_output – output validation failed according to the ability’s schema.
ability_invalid_execute_callback – the ability’s execute callback is not callable.
rest_ability_not_found – the requested ability is not registered.
rest_ability_category_not_found – the requested category is not registered.

通用API文档

REST API 端点

概述

关键要点

代码示例

注意事项

User access

Controlling REST API Exposure

Schema

Ability Object

List Abilities

Definition

Arguments

Example Request

Example Response

List Categories

Definition

Arguments

Example Request

Example Response

Retrieve a Category

Definition

Arguments

Example Request

Example Response

Retrieve an Ability

Definition

Arguments

Example Request

Example Response

Execute an Ability

Definition

Arguments

Example Request (GET)

Example Request (POST)

Example Request (DELETE)

Example Response (Success)

Example Response (Error)

Authentication

Using Application Passwords

Error Responses