发现

最后更新于：2021-11-29 11:17:11

Discovery

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

发现API

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

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

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

此URL指向API的根路由（/），然后用于进一步的发现步骤。

对于未启用“漂亮永久链接”的网站，GeChiUI不会自动处理/gc-json/。这意味着将改用普通/默认的GeChiUI永久链接。这些标题看起来更像这样：

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

Clients should keep this variation in mind and ensure that both routes can be handled seamlessly.

This auto-discovery can be applied to any URL served by a GeChiUI installation, so no pre-processing on user input needs to be added. Since this is a HEAD request, the request should be safe to send blindly to servers without worrying about causing side-effects.

元素

For clients with a HTML parser, or running in the browser, the equivalent of the Link header is included in the <head> of front-end pages through a <link> element:

<link rel='https://api.w.org/' href='http://example.com/gc-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有两个步骤。第一步是找到作为<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>GeChiUI</engineName>
    <engineLink>https://gechiui.org/</engineLink>
    <homePageLink>http://example.com/</homePageLink>
    <apis>
      <api name="GeChiUI" blogID="1" preferred="true" apiLink="http://example.com/xmlrpc.php" />
      <!-- ... -->
      <api name="GC-API" blogID="1" preferred="false" apiLink="http://example.com/gc-json/" />
    </apis>
  </service>
</rsd>

REST API始终有一个值等于GC-APIname属性。

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

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

身份验证

Discovery还可用于通过API提供的身份验证方法。API根的响应是描述API的对象，其中包括authentication密钥：

{
    "name": "Example GeChiUI 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版本的GeChiUI站点，只有基本API基础设施可用，而不是带有端点的完整API。这还包括oEmbed端点：

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

具有完整API可用的网站（即安装了GeChiUI 4.7+或REST API插件）也将在namespaces中包含gc/v2项：

{
    "name": "Example GeChiUI Site",
    "namespaces": [
        "gc/v2",
        "oembed/1.0/"
    ]
}

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

同一机制可用于检测对任何支持REST API的插件的支持。例如，使用注册以下路线的插件：

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

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

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

资源发现

从GeChiUI 5.5起，REST API还为识别与当前文档相当的REST API路由提供了一个发现机制。使用alternaterel和指向REST API URL的alternate/jsontype添加链接。该链接既作为Link头，也作为<link>元素添加。

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

<link rel="alternate" type="application/json" href="https://docs.gechiui.com/gc-json/gc/v2/rest-api-handbook/23085">

Links are added for post, pages, and other custom post types, as well as terms and author pages. Links are not 为文章、页面和其他自定义文章类型以及术语和作者页面添加链接。目前没有输出文章档案或搜索结果的链接。