发现-WordPress REST API 手册-果果开发

当您的客户端与未知站点通信时，您需要发现该站点具备哪些功能以及其配置方式。根据您想要发现的内容，有几个步骤可供选择。

发现 API

连接到站点的第一个步骤是确定该站点是否启用了 API。通常，您将处理来自用户输入的 URL，因此您访问的站点可能是任何内容。发现步骤可让您验证 API 是否可用，并指示如何访问它。

Link 头部

处理发现的首选方法是向提供的地址发送 HEAD 请求。REST API 会自动在所有前端页面上添加一个 Link 头部，如下所示：

Link: <http://example.com/wp-json/>; rel="https://api.w.org/"

此 URL 指向 API 的根路由 (/)，随后用于进一步的发现步骤。

对于未启用“漂亮固定链接”的站点，/wp-json/ 不会被 WordPress 自动处理。这意味着将使用正常/默认的 WordPress 固定链接。这些头部的样子更像这样：

Link: <http://example.com/?rest_route=/>; rel="https://api.w.org/"

客户端应牢记这种变体，并确保能无缝处理这两种路由。

这种自动发现适用于由 WordPress 安装提供的所有 URL，因此无需对用户输入进行预处理。由于这是 HEAD 请求，因此可以安全地盲目地向服务器发送请求，而无需担心引起副作用。

Element

对于具有 HTML 解析器的客户端或在浏览器中运行的客户端，Link 头部的等效项包含在前端页面的 <head> 中的 <link> 元素里：

<link rel='https://api.w.org/' href='http://example.com/wp-json/' />

浏览器内的 Javascript 可以通过 DOM 访问此内容：

// jQuery method
var $link = jQuery( 'link[rel="https://api.w.org/"]' );
var api_root = $link.attr( 'href' );

// Native method
var links = document.getElementsByTagName( 'link' );
var link = Array.prototype.filter.call( links, function ( item ) {
    return ( item.rel === 'https://api.w.org/' );
} );
var api_root = link[0].href;

对于浏览器内客户端或无法访问 HTTP 头部的客户端，这可能是发现 API 更实用的方法。这与 Atom/RSS 源发现类似，因此现有的相关代码也可以自动适配。

RSD (Really Simple Discovery)

对于支持 XML-RPC 发现的客户端，RSD 方法可能更适用。这是一种基于 XML 的发现格式，通常用于 XML-RPC。RSD 有两个步骤。第一步是找到 RSD 端点，它以 <link> 元素的形式提供：

<link rel="EditURI" type="application/rsd+xml" title="RSD" href="http://example.com/xmlrpc.php?rsd" />

第二步是获取 RSD 文档并解析可用的端点。这涉及对如下文档使用 XML 解析器：

<?xml version="1.0" encoding="utf-8"?>
<rsd version="1.0" xmlns="http://archipelago.phrasewise.com/rsd">
  <service>
    <engineName>WordPress</engineName>
    <engineLink>https://wordpress.org/</engineLink>
    <homePageLink>http://example.com/</homePageLink>
    <apis>
      <api name="WordPress" blogID="1" preferred="true" apiLink="http://example.com/xmlrpc.php" />
      <!-- ... -->
      <api name="WP-API" blogID="1" preferred="false" apiLink="http://example.com/wp-json/" />
    </apis>
  </service>
</rsd>

REST API 始终有一个 name 属性，其值等于 WP-API。

RSD 是自动发现的最不推荐的方法，原因有二。基于 RSD 的发现的第一步涉及解析 HTML 以首先找到 RSD 文档本身，这等同于 <link> 元素的自动发现。然后需要另一步来解析 RSD 文档，这需要完整的 XML 解析器。

在可能的情况下，我们建议避免使用基于 RSD 的发现，因为其复杂性较大，但如果现有 XML-RPC 客户端已启用 RSD 解析器，则可能更喜欢使用此方法。对于希望将 REST API 作为代码库的渐进式增强的 XML-RPC 客户端，这种方法避免了需要支持不同形式的发现。

认证发现

API 还提供了通过 API 可用的认证方法的发现功能。API 根节点的响应是一个描述 API 的对象，其中包括一个 authentication 键：

{
    "name": "Example WordPress Site",
    "description": "YOLO",
    "routes": { ... },
    "authentication": {
        "oauth1": {
            "request": "http://example.com/oauth/request",
            "authorize": "http://example.com/oauth/authorize",
            "access": "http://example.com/oauth/access",
            "version": "0.1"
        }
    }
}

authentication 的值是一个映射（关联数组），将认证方法 ID 映射到认证选项。此处可用的选项特定于认证方法本身。有关特定认证方法的选项，请参阅认证文档。

扩展发现

一旦发现了 API，下一步就是检查 API 支持哪些内容。API 的索引暴露了 namespaces 项，其中包含受支持的 API 扩展。

对于使用 4.4 到 4.6 版本的 WordPress 站点，仅提供了基础 API 基础设施，而没有带端点的完整 API。这也包括 oEmbed 端点：

{
    "name": "Example WordPress Site",
    "namespaces": [
        "oembed/1.0/"
    ]
}

拥有完整 API 的站点（即安装了 WordPress 4.7+ 或 REST API 插件）将在 namespaces 中包含 wp/v2 项：

{
    "name": "Example WordPress Site",
    "namespaces": [
        "wp/v2",
        "oembed/1.0/"
    ]
}

在尝试使用任何核心端点之前，您应确保通过检查 wp/v2 支持来确认 API 受支持。WordPress 4.4 为所有站点启用了 API 基础设施，但并未包含 wp/v2 下的核心端点。核心端点是在 WordPress 4.7 中添加的。

可以使用相同的机制来检测支持 REST API 的任何插件的支持情况。例如，考虑一个注册以下路由的插件：

<?php
register_rest_route( 'testplugin/v1', '/testroute', array( /* ... */ ) );

这将把 testplugin/v1 命名空间添加到索引中：

{
    "name": "Example WordPress Site",
    "namespaces": [
        "wp/v2",
        "oembed/1.0/",
        "testplugin/v1"
    ]
}

资源发现

自 WordPress 5.5 起，REST API 还提供了一种发现机制，用于识别当前文档对应的 REST API 路由。会添加一个带有 rel 为 alternate 且 type 为 application/json 的链接，指向 REST API URL。该链接同时作为 Link 头部和 <link> 元素添加。

例如，在此页面的 <head> 部分中，会出现以下 <link>。

<link rel="alternate" type="application/json" href="https://developer.wordpress.org/wp-json/wp/v2/rest-api-handbook/23085">

文章、页面和其他自定义文章类型以及分类法（术语）和作者页面都会添加链接。目前，文章归档或搜索结果尚未输出链接。