WordPress中文开发手册

发现

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

##发现API

连接到网站的第一步是找出网站是否启用了API。 通常，您将使用用户输入的URL，因此您访问的网站可能是任何东西。 发现步骤允许您验证API是否可用，以及如何访问它。

##链接头

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

链接：http://example.com/wp-json/; rel =“https://api.w.org/”>

该URL指向API的根路径（/），然后将其用于进一步的发现步骤。

对于没有启用“漂亮的永久链接”的网站，/ wp-json /不会被WordPress自动处理。 这意味着将使用正常/默认的WordPress固定链接。 这些标题看起来更像这样：

链接：http://example.com/?rest_route=/; rel =“https://api.w.org/”

客户应牢记这种变化，并确保两条路线能够无缝地处理。

此自动发现可以应用于WordPress安装服务的任何URL，因此不需要添加用户输入的预处理。 由于这是HEAD请求，所以请求应该安全地盲目发送到服务器，而不用担心会产生副作用。

##元素

对于具有HTML解析器或在浏览器中运行的客户端，通过“”元素，前端页面的中包含了Link标题的等价物：

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

In-browser Javascript can access this via the 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 feed发现类似，因此也可以自动为此目的使用现有的代码
改为代替。

RSD（真正简单发现）

对于支持XML-RPC发现的客户端，RSD方法可能更适用。 这是一种通常用于XML-RPC的基于XML的发现格式。 RSD有两个步骤。 第一步是找到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始终具有名称属性，其值等于WP-API。

RSD是自动发现的最不喜欢的方法，有几个原因。 基于RSD的发现的第一步涉及解析HTML以首先找到RSD文档本身，这相当于元素自动发现。 然后，它需要另一个步骤来解析RSD文档，这需要一个完整的XML解析器。

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

##认证发现

发现也可用于通过API可用的身份验证方法。 API根的响应是描述API的对象，其中包含一个验证密钥：

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

认证值是认证方法ID与认证选项的映射（关联数组）。 这里提供的选项特定于身份验证方法本身。 有关特定身份验证方法的选项，请参阅身份验证文档。

##扩展发现

一旦您发现了API，下一步就是检查API支持的内容。 API的索引公开了命名空间项，其中包含支持的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项目：

{
    "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( /* ... */ ) );

This would add the testplugin/v1 namespace to the index:

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