WordPress REST API手册(四 | 4):发现

当您的客户与未知站点交谈时,您需要了解该站点的功能以及该站点的配置方式。这有几个步骤,具体取决于您需要发现什么。

发现 API

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

顶部↑

处理发现的首选方法是将 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 请求,因此该请求应该可以安全地盲目发送到服务器,而不必担心引起副作用。

元素

对于具有 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(真正简单的发现)

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

<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>Element 自动发现。然后它涉及解析 RSD 文档的另一个步骤,这需要完整的 XML 解析器。

由于复杂性,我们建议尽可能避免基于 RSD 的发现,但如果现有 XML-RPC 客户端已经启用了 RSD 解析器,他们可能更喜欢使用此方法。对于希望使用 REST API 作为代码库的渐进增强的 XML-RPC 客户端,这避免了需要支持不同形式的发现。

身份验证发现

发现也可用于通过 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 插件)也将包含该wp/v2项目namespaces

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

在尝试使用任何核心端点之前,您应该确保通过检查支持来检查 API 是否受wp/v2支持。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 路由。添加一个链接,其中一个ofrelalternate一个指向 REST API url。该链接作为标题元素添加。typealternate/jsonLink<link>

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

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

为帖子、页面和其他自定义帖子类型以及术语和作者页面添加了链接。当前不为帖子存档或搜索结果输出链接。

THE END
评论 抢沙发
头像
欢迎您留下宝贵的见解!
提交
头像

昵称

取消
昵称表情代码图片