发现 · 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>”元素，前端页面的<head>中包含了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>”元素的形式提供： ``` <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文档本身，这相当于<link>元素自动发现。然后，它需要另一个步骤来解析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" ] } ```