发现
当您的客户与未知站点对话时,您需要了解该站点的功能以及该站点的配置方式。这有几个步骤,具体取决于您需要发现的内容。
发现 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 文档本身,这相当于 Element <link>
autodiscovery。然后它涉及解析 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 路由。添加一个带有rel
of 的链接,其中alternate
一个指向 REST API url。该链接被添加为标题和元素。type``application/json``Link``<link>
例如,在<head>
此页面的部分中,出现以下内容<link>
。
<link rel="alternate" type="application/json" href="https://developer.wordpress.org/wp-json/wp/v2/rest-api-handbook/23085">
为帖子、页面和其他自定义帖子类型以及术语和作者页面添加了链接。当前不为帖子存档或搜索结果输出链接。