REST API 端点-WordPress通用API手册-果果开发

WordPress Abilities API 提供 REST 端点，允许外部系统通过 HTTP 请求发现和执行能力。

用户访问

访问所有 Abilities REST API 端点需要已认证的用户（请参阅认证部分）。执行单个 Ability 的访问权限根据 Ability 的 permission_callback() 进行限制。

控制 REST API 暴露

默认情况下，注册的 abilities 不通过 REST API 暴露。您可以通过在注册 ability 时使用 show_in_rest meta 来控制单个 ability 是否出现在 REST API 中：

show_in_rest => true：该 ability 列在 REST API 响应中，并可通过 REST 端点执行。
show_in_rest => false（默认）：该 ability 从 REST API 列表中隐藏，无法通过 REST 端点执行。该 ability 仍可通过 wp_get_ability() 和 $ability->execute() 供内部 PHP 使用。

meta 为 show_in_rest => false 的 abilities 如果通过 REST 端点访问，将返回 rest_ability_not_found 错误。

模式

Abilities API 端点位于 /wp-abilities/v1 命名空间下。

能力对象

Abilities 以 JSON 表示，结构如下：

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

能力列表

定义

GET /wp-abilities/v1/abilities

参数

page (integer): Collection 的当前页。默认值：1。
per_page (integer): 每页返回的最大项目数。默认值：50，最大值：100。
category (string): 按分类 slug 过滤 abilities。

请求示例

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

响应示例

[
  {
    "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
      }
    }
  }
]

分类列表

定义

GET /wp-abilities/v1/categories

参数

page (integer): Collection 的当前页。默认值：1。
per_page (integer): 每页返回的最大项目数。默认值：50，最大值：100。

请求示例

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

响应示例

[
  {
    "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"
        }
      ]
    }
  }
]

获取单个分类

定义

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

参数

slug (string): 分类的唯一 slug。

请求示例

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

响应示例

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

获取单个能力

定义

GET /wp-abilities/v1/(?P<namespace>[a-z0-9-]+)/(?P<ability>[a-z0-9-]+)

参数

namespace (string): Ability 名称的命名空间部分。
ability (string): Ability 名称部分。

请求示例

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

响应示例

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

执行能力

Abilities 通过 /run 端点执行。所需的 HTTP 方法取决于 ability 的功能和 annotations：

Read-only abilities 必须使用 GET (readonly: true)
Regular abilities 在只读时（readonly: true）必须使用 GET，在需要输入时（readonly: false）必须使用 POST
Destructive abilities (destructive: true) 必须使用 DELETE

这种区分确保了只读操作使用安全的 HTTP 方法，这些方法可以被缓存且不会修改服务器状态。

定义

GET|POST|DELETE /wp-abilities/v1/(?P<namespace>[a-z0-9-]+)/(?P<ability>[a-z0-9-]+)/run

参数

namespace (string): Ability 名称的命名空间部分。
ability (string): Ability 名称部分。
input (integer|number|boolean|string|array|object|null): 可选的 ability 输入数据，由其输入 schema 定义。
对于 GET 和 DELETE 请求：作为 input 查询参数传递（URL 编码的 JSON）
对于 POST 请求：在 JSON body 中传递

请求示例 (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"

请求示例 (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

请求示例 (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"

响应示例 (Success)

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

响应示例 (Error)

{
  "code": "ability_invalid_permissions",
  "message": "Ability \"my-plugin/update-option\" does not have necessary permission.",
  "data": {
    "status": 403
  }
}

Authentication

Abilities API 支持所有 WordPress REST API 身份验证方法：

Cookie 身份验证（同源请求）
应用程序密码（推荐用于外部访问）
自定义身份验证插件

使用应用密码

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

错误响应

API 返回标准的 WordPress REST API 错误响应，包含以下常见代码：

ability_missing_input_schema – 该能力需要输入，但未提供。
ability_invalid_input – 根据能力的模式，输入验证失败。
ability_invalid_permissions – 当前用户没有执行该能力的权限。
ability_invalid_output – 根据能力的模式，输出验证失败。
ability_invalid_execute_callback – 能力的执行回调不可调用。
rest_ability_not_found – 请求的能力未注册。
rest_ability_category_not_found – 请求的类别未注册。