WordPress REST API：它是什么以及如何使用

Tu WordPress no es solo una web: también es un servidor de datos. Desde la versión 4.7, la REST API de WordPress viene integrada en el núcleo y expone entradas, páginas, usuarios, medios y taxonomías en formato JSON, listos para ser leídos o modificados desde cualquier aplicación externa: una app móvil, un script de automatización, otra web o un panel de control a medida. Es la tecnología que hace funcionar el editor de bloques, la que usan miles de integraciones y la puerta de entrada al llamado WordPress «headless». Y, sin embargo, muchos usuarios avanzados no la han explorado nunca. En esta guía práctica veremos qué es exactamente la REST API de WordPress, cómo están organizados sus endpoints, cómo autenticarte de forma segura con Application Passwords, cómo leer y crear contenido con ejemplos reales (desde el navegador, con JavaScript y con PHP), cómo crear tus propios endpoints y qué precauciones de seguridad conviene tomar. Todo con código funcional que puedes probar hoy en tu propia web.

Qué es la REST API de WordPress y para qué sirve 主要端点：API 地图使用应用程序密码进行身份验证读写内容：JavaScript 示例使用 register_rest_route 创建你自己的端点安全：暴露什么和保护什么常见问题结论

Qué es la REST API de WordPress y para qué sirve

REST API 是一种接口，允许两个系统使用协议的经典操作通过 HTTP 进行通信： GET 用于读取， POST 用于创建， PUT/PATCH 用于更新和 DELETE 用于删除。响应以 JSON 格式到达，这是一种任何语言都能理解的轻量级文本格式。对于 WordPress 而言，这意味着您从仪表盘管理的所有内容（文章、页面、评论、分类、用户、媒体）也都有一个结构化且官方的“后门”供机器使用。

WordPress REST API 发挥作用的实际用例：

自动化： 通过脚本、电子表格或 n8n 和 Make 等工具发布或更新内容。
无头 WordPress： 仅将 WordPress 用作内容管理器，并使用 React、Vue 或 Astro 构建前端。
移动应用程序： WordPress 官方应用程序完全基于此 API 运行。
网站集成： 在一个网站上显示另一个网站的最新文章，同步目录，集中发布。
定制面板： 无需通过 wp-admin 即可在 WordPress 中读写的仪表盘。

API 也是与人工智能进行现代集成的基础：例如插件 AI Engine，将您的 WordPress 变成一个 AI 代理，它们依赖于它来向外部助手公开内容。

主要端点：API 地图

一切都始于一个 URL： https://tudominio.com/wp-json/。在浏览器中打开它，您将看到可用路由的完整索引。核心端点挂载在命名空间 wp/v2:

端点	内容
`/wp-json/wp/v2/posts`	博客文章
`/wp-json/wp/v2/pages`	页面
`/wp-json/wp/v2/media`	媒体库
`/wp-json/wp/v2/categories`	分类
`/wp-json/wp/v2/tags`	Etiquetas
`/wp-json/wp/v2/users`	用户（公开数据）
`/wp-json/wp/v2/comments`	评论
`/wp-json/wp/v2/search`	全局搜索

每个集合端点都支持非常有用的查询参数： ?per_page=5 限制结果， ?search=wordpress 搜索， ?categories=12 按类别筛选， ?orderby=date&order=asc 排序和 ?_fields=id,title,link 只返回您请求的字段，从而减轻响应负担。对于特定项目，会添加其 ID： /wp-json/wp/v2/posts/123.

WordPress 的 JSON 响应未经格式化，以难以阅读的单行形式呈现。一个工作流程技巧：将响应粘贴到我们的免费的 JSON 格式化工具和验证器您将获得缩进且彩色的树状结构，以便舒适地检查它。

分页：您应该了解的标头

集合端点每次请求最多返回 100 个项目（默认为 10 个）。为了遍历大型目录，API 在每个响应中包含两个 HTTP 标头： X-WP-Total，包含项目总数，以及 X-WP-TotalPages，根据您的可用页面数量 per_page。只需通过添加来迭代 ?page=2, ?page=3 依此类推，直到达到最后一页。如果您请求一个不存在的页面，API 将返回一个代码为 400 的错误 rest_post_invalid_page_number，一个方便的信号，用于在导出或迁移脚本中停止循环。

使用应用程序密码进行身份验证

读取公共内容不需要身份验证，但创建、编辑或删除则需要。自 WordPress 5.6 起，集成且推荐的方法是 应用程序密码 （应用程序密码）：特定于应用程序的密钥，可单独撤销，且不会泄露您的真实密码。

要创建一个：进入 用户 → 个人资料，向下滚动到“应用程序密码”，输入一个描述性名称（例如“发布脚本”）并点击创建。WordPress 将一次性显示一个格式为...的密钥 xxxx xxxx xxxx xxxx xxxx xxxx。将其保存在密码管理器或环境变量文件中，绝不要保存在源代码中。

密钥用于 HTTP Basic 认证：用户名和应用程序密码以 Base64 编码在请求头中 Authorization。必要条件：网站必须通过 HTTPS 提供服务，因为在纯 HTTP 中，凭据会暴露。

从终端使用 curl 进行快速测试：

curl -X POST https://tudominio.com/wp-json/wp/v2/posts \
  -u "tu_usuario:xxxx xxxx xxxx xxxx xxxx xxxx" \
  -H "Content-Type: application/json" \
  -d '{"title":"Borrador desde la API","status":"draft"}'

如果响应是包含新草稿 ID 的 JSON，则认证成功。每个权限都取决于用户的角色：订阅者的应用程序密码将无法发布文章。

读写内容：JavaScript 示例

让我们通过...看看 API 的实际应用 fetch，就像你在外部网站或应用程序中那样。首先，读取博客的最新文章（无需认证，公共内容）：

const API = 'https://tudominio.com/wp-json/wp/v2';

async function ultimasEntradas() {
  const res = await fetch(`${API}/posts?per_page=5&_fields=id,title,link,date`);
  if (!res.ok) {
    throw new Error('Error HTTP ' + res.status);
  }
  const posts = await res.json();
  posts.forEach((post) => {
    console.log(`${post.date} — ${post.title.rendered} — ${post.link}`);
  });
}

ultimasEntradas();

现在，使用应用程序密码进行认证来创建条目（这必须在服务器环境或私有脚本中执行，绝不能在访问者的浏览器中执行，因为它会暴露密钥）：

const usuario = 'tu_usuario';
const clave   = 'xxxx xxxx xxxx xxxx xxxx xxxx';
const token   = Buffer.from(`${usuario}:${clave}`).toString('base64');

async function crearEntrada() {
  const res = await fetch('https://tudominio.com/wp-json/wp/v2/posts', {
    method: 'POST',
    headers: {
      'Authorization': `Basic ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      title: 'Publicado por la REST API',
      content: '<p>Este contenido lo ha creado un script.</p>',
      status: 'draft',
      categories: [12],
    }),
  });
  const data = await res.json();
  if (!res.ok) {
    throw new Error(data.message || 'Error al crear la entrada');
  }
  console.log('Creada con ID', data.id, '→', data.link);
}

crearEntrada();

注意...的细节 title.rendered 读取时：API 将文本字段作为带有变体的对象返回 rendered （最终 HTML）并且，如果你已通过编辑权限认证并添加 ?context=edit，也 raw （原始内容）。

使用 register_rest_route 创建你自己的端点

核心 API 涵盖标准内容，但当你暴露自己的数据时，真正的潜力就来了。借助 register_rest_route() 你可以在自己的命名空间下创建自定义路由。完整示例：一个返回基本站点统计信息、带有验证参数和权限控制的端点：

<?php
add_action( 'rest_api_init', function () {
    register_rest_route( 'biblioweb/v1', '/estadisticas', array(
        'methods'             => 'GET',
        'callback'            => 'biblioweb_api_estadisticas',
        'permission_callback' => '__return_true', // Endpoint público de solo lectura.
        'args'                => array(
            'tipo' => array(
                'default'           => 'post',
                'sanitize_callback' => 'sanitize_key',
                'validate_callback' => function ( $valor ) {
                    return post_type_exists( $valor );
                },
            ),
        ),
    ) );
} );

function biblioweb_api_estadisticas( WP_REST_Request $request ) {
    $tipo     = $request->get_param( 'tipo' );
    $conteo   = wp_count_posts( $tipo );
    $usuarios = count_users();

    return rest_ensure_response( array(
        'tipo'        => $tipo,
        'publicados'  => (int) $conteo->publish,
        'borradores'  => (int) $conteo->draft,
        'usuarios'    => (int) $usuarios['total_users'],
        'generado_en' => current_time( 'mysql' ),
    ) );
}

保存此代码（在插件或代码片段中）后，你的新端点将在...响应 https://tudominio.com/wp-json/biblioweb/v1/estadisticas?tipo=page。三条黄金法则：始终使用带有版本的自定义命名空间（biblioweb/v1），定义 permission_callback 明确地（从 WordPress 5.5 开始是强制性的；对于私有端点，请使用类似...的检查 current_user_can( 'edit_posts' )）并验证每个输入参数。完整参考资料在 WordPress REST API 官方手册.

安全：暴露什么和保护什么

WordPress REST API 在设计上是安全的（它只暴露已公开的内容，并要求写入权限），但最好调整一些细节：

用户枚举： 端点 /wp/v2/users 列出已发布内容的作者，这使得攻击者更容易获取有效的用户名。许多安全插件会限制它；也可以通过代码过滤以要求认证。
强制 HTTPS： 没有 SSL 证书，应用程序密码将以明文传输。这条规则没有合理的例外。
最小权限原则： 使用其角色仅具有集成所需权限的用户创建应用程序密码，并在不再使用时撤销它们。
不要粗暴地禁用 API： 块编辑器和许多插件都依赖于它。如果你想限制它，请使用过滤器要求认证 rest_authentication_errors 而不是完全阻止它。
限制暴露面： 公共自定义端点应该只返回你不在乎任何人可见的数据。

这些预防措施符合一般的强化策略；如果你想回顾它，我们有一份指南，其中包含增强 WordPress 安全性的技巧.

常见问题

我的网站上 WordPress REST API 活跃吗？

几乎可以肯定，是的：它从 WordPress 4.7 (2016) 开始默认启用。通过访问...来检查 tudominio.com/wp-json/：如果你看到一个包含你的站点名称和路由列表的 JSON，那么它正在运行。如果返回 404，请检查永久链接或是否有安全插件正在阻止它。

启用 API 危险吗？

不比发布网站更危险。读取 API 只暴露你网站上已公开的内容，并且所有写入操作都需要认证和权限。两个明智的设置是限制用户列表并确保所有内容都通过 HTTPS 提供。完全禁用它通常会带来比避免的更多问题。

我可以使用 API 处理自定义文章类型和自定义字段吗？

是的。如果自定义文章类型是用...注册的，它们会出现在 API 中。 show_in_rest => true，并获得自己的端点（例如 /wp/v2/proyecto）。自定义字段通过...暴露 register_post_meta() 也标记为 show_in_rest，或使用字段 meta 条目本身的，如果创建它们的插件支持的话。

REST API 和 WPGraphQL 之间有什么区别？

REST API 是核心标准：每种数据类型都有其端点，并且响应具有固定结构。GraphQL（通过 WPGraphQL 插件）允许在单个查询中精确请求你需要的字段，这在复杂的无头项目中很受欢迎。对于自动化、集成和大多数项目，REST API 更简单，不需要插件，并且得到官方支持。

结论

WordPress REST API 将你的网站变成一个可编程平台：在...下的清晰端点索引 /wp-json/wp/v2/，基于 HTTPS 的应用程序密码集成认证，以及通过自定义路由扩展地图的可能性 register_rest_route()。凭借本指南所学，你可以从任何应用程序读取公共内容，通过认证脚本发布和编辑，暴露带有验证和权限的自定义数据，并采取适当的安全预防措施。掌握它的最佳途径是实践：打开 tudominio.com/wp-json/wp/v2/posts?per_page=3 在浏览器中，将响应通过 JSON 格式化工具处理以理解其结构，创建你的第一个应用程序密码，并从 curl 发送一个草稿。十五分钟内，你将跨越从使用 WordPress 到用 WordPress 编程的门槛。