REST API¶

在 XenForo 2.1 中，添加了 REST API。这使您可以通过编程的方式与 XenForo 安装的许多区域进行交互。

要访问 API，需要通过管理员控制面板生成密钥。未经认证的 API 没有办法访问，此时用户也不能自己生成密钥来访问 API。

特定 XenForo 安装的 API 可通过 <XenForo 基本 URL>/api/ 访问。所有端点都以该 URL 为前缀。例如，如果 XenForo 安装在 https://example.com/community/，那麽API URL将以 https://example.com/community/api/ 开头。在本例中，访问线程列表可通过 https://example.com/community/api/threads/ 进行。

默认情况下 API 是激活的。如果需要，可以通过在 src/config.php 中添加以下内容来快速关闭所有 API 访问：

$config['enableApi'] = false;

API 密钥¶

通过管理员控制面板到 设置 > API 密钥 创建 API 密钥。由于生成 API 密钥可以允许访问高度特权的数据，因此只有超级管理员可以访问本系统。当生成 API 密钥时，所有超级管理员都会収到一封邮件，以确保请求有效。

创建密钥后，将生成一个随机字符串，该字符串将用于通过 API 进行身分验证。将此密钥保密是很重要的。如果您认为 API 密钥已被盗用，你应该立即重新生成新的密钥并更新任何使用旧密钥的代码。

密钥类型¶

所有的 API 访问都是在特定用户的 Context 中进行的。例如，如果我以 "John" 的身分访问 API，并且我提出了一个发布主题的请求，那麽这个主题将由 "John" 创建。在大多数情况下，API 也会遵守为这个用户指定对应的权限，所以他们不能访问他们在正常浏览论坛时看不到的数据。

为了对此进行控制，共有三种类型的 API 密钥：

访客密钥 - 此密钥总是以访客用户身分存取 API。这些请求将始终遵守访客的权限。例如，如果客人不能回覆主题，那麽回覆主题的 API 请求将生成一个没有权限的错误。
用户密钥 - 这个密钥总是以指定用户的身分访问 API，并始终遵守该用户的权限，类似于访客密钥。
超级用户密钥 - 这个密钥可以通过传递一个额外的值，以任何用户的身分访问 API。（可选）此密钥可以绕过用户发出请求的权限，从而允许他们运行操作或查看通常不具有访问权限的内容。

超级用户密钥对于与其他系统或应用程序的整合非常有用。例如，您可能会与第三方 CMS 整合，每当您发布一篇新文章时，该 CMS 就会创建一个主题。这种类型的密钥将允许您根据文章作者或在用户通常不能发布的论坛中创建一个不同用户的主题。

密钥作用域¶

为了帮助限制被泄露的密钥所造成的损害，每个密钥都可以控制其可以访问的 API 作用域。作用域限制了对 API 区域的访问，与用户的请求权限无关。

API 中的每个端点都会被一个或多个作用域所复盖。如果 API 没有被授予任何这些作用域，则请求将失败。

为了安全起见，我们建议您仅为密钥授予所需的作用域。如果您在以后需要其他的作用域，则可以在需要时添加它们。

访问 API¶

一旦知道访问 API 的 URL 并获得密钥后，就可以开始对其发出请求。

所有的 API Response 都将以 JSON 格式返回，除非是特别要求二进制文件（例如，下载附件时）。错误将返回一个 400 范围内的 Response 状态码。成功的请求将返回一个 200 状态码。虽然不常用，但重定向将返回一个 300 范围的状态码。

Request body 必须使用 application/x-www-form-urlencoded 编码发送，或者，如果是上传文件，则使用 multipart/form-data 编码发送。参数也可以通过查找字符串来传递。

所有 Request 数据必须使用 UTF-8 字符集。

Request 必须通过 XF-API-Key Header 传递要使用的 API 密钥。所有 Request 中都必须有这个密钥。

如果选择的 API 密钥是超级用户密钥，你可以通过 XF-API-User Header 传递 Context User 的用户ID。如果没有传递用户 ID，Context 将默认为访客。

如果 Request 是用超级用户密钥发出的，并且你希望绕过 Context User 的权限，则可以通过将 api_bypass_permissions 参数设置为 1 来实现。(这个参数可以通过 query string 或作为 Request body 的一部分来进行传递。)

错误处理¶

当遇到 Error 时，response 状态码将在 400 范围内。有时，可能会出现 500 范围的错误，不过这表明服务器无法处理该 request。 API 可能被暂时关闭，或者发生了其他服务器错误。

错误消息具有标准格式。这是一个例子：

{
    "errors": [
        {
            "code": "api_key_not_found",
            "message": "未找到 Request 中提供的 API 密钥。",
            "params": []
        }
    ]
}

最上层将是一个帯有 errors key 的物件。这将是包含 1 个或多个 entry 的数组。每个 entry 都是一个物件，参数如下：

code - 这是机器可以读懂的错误码。有许多可能的错误码，因为它们取决于情况。
message - 人类可以读懂的错误消息。这可能会改变，也可能会被翻译，不应该用于识别错误类型。
params - 这是触发错误相关的 key-value 参数表表。它们可以补充错误码和消息，以提供有关错误的更多明确的详细消息。

API 端点¶

该 API 具有许多 Endpoints 和可以采取的措施。将来可能会添加其他 Endpoint 和数据。

查看 API 端点文档

该 Endpoint 文档是根据 API 数据和代码中的注释生成的。它将随着时间的推移进行扩展和更新。