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 功能：

PHP 
$config['enableApi'] = false;

API 密钥​

API 密钥通过管理员控制面板创建，具体操作为：进入设置 > API 密钥。由于生成的 API 密钥可以访问高度机密的数据，因此只有超级管理员才能访问此模块。所有超级管理员都会在 API 密钥生成时收到电子邮件，以确保请求有效。

密钥生成时，系统会生成一个随机字符串，用于 API 身份验证。请务必妥善保管此密钥。如果您认为 API 密钥已被泄露，应立即重新生成密钥，并更新所有使用旧密钥的代码。

密钥类型​

所有 API 访问均在特定用户的上下文中进行。例如，如果我以“John”的身份访问 API 并发出一个发布主题的请求，则该主题将由“John”创建。在大多数情况下，API 还会遵守为该用户指定的权限，因此，他们无法访问在正常浏览网站时看不到的数据。

为了实现访问权限控制，API 密钥分为三种类型：

类型描述
访客密钥此密钥始终以访客身份访问 API。这些请求将始终遵循访客权限。例如，如果访客无法回复帖子，则回复帖子的 API 请求将返回无权限错误。
用户密钥此密钥始终以指定用户的身份访问 API，并始终遵循该用户的权限。
超级密钥通过向此密钥传递一个附加值，它可以作为任何用户来访问 API。此外，此密钥还可以绕过请求用户的权限，允许他们执行通常无权访问的操作或查看内容。

超级密钥常用于和其它系统或应用程序集成。例如可以将 XenForo 集成至第三方内容管理系统 (CMS)，以令该系统在发布新文章时自动创建一个主题帖。

这种密钥还允许以不同的用户身份创建帖子。

密钥作用域​

为了尽可能降低密钥泄露造成的损失，每个密钥都可以控制其可访问的 API 作用域。作用域限制了对 API 特定区域的访问，而与请求用户的权限无关。

API 中的每个端点都受一个或多个作用域的约束。如果 API 没有被授予任何作用域，则请求将失败。

出于安全考虑，建议仅授予密钥所需的作用域。如果以后需要其它作用域，可以随时添加。

访问 API​

在确认了所访问 API 的 URL 并拥有其密钥之后，便可开始向其发送请求。

所有 API 响应均以 JSON 格式返回，除非明确请求二进制文件（例如下载附件）。错误始终返回400左右范围的响应代码。成功的请求将返回200代码，偶尔会返回300左右范围内的代码，这些代码通常代表重定向。

请求载荷必须使用application/x-www-form-urlencoded编码，如果要上传文件，则必须使用multipart/form-data编码。参数也可以通过查询字符串传递，但对于非GET请求，强烈建议通过请求载荷传递参数。

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

请求必须通过XF-Api-Key标头传递要使用的 API 密钥。所有请求都必须包含此标头。

如果所选的 API 密钥是超级密钥，可以通过XF-Api-User标头传递上下文用户的用户 ID。如果未传递用户 ID，则上下文将默认为访客用户。

如果使用超级密钥发出请求，且希望绕过上下文用户的权限，则可以通过设置api_bypass_permissions参数为1来针对每个请求进行设置。此参数可以通过查询字符串传递，也可以作为请求正文的一部分传递。

错误处理​

遇到错误时，响应代码通常为400左右的数值。偶尔也会出现500范围的错误，此代码表示服务器无法处理请求——可能是 API 暂时被禁用，或者发生了其它服务器错误。

错误消息采用标准化格式。以下是一个示例：

JSON 
{
    "errors": [
        {
            "code": "api_key_not_found",
            "message": "请求未能提供 API 密钥。",
            "params": []
        }
    ]
}

顶层对象包含一个名为errors的键。该键是一个数组，包含一个或多个条目。每个条目都是一个对象，包含以下参数：

键名描述
code机读错误代码。错误代码有很多种，取决于具体情况。
message错误描述的人类可读版本。此版本可能会被修改或翻译，不应用于严格地识别错误类型。
params这是与触发的错误相关的键值参数列表。它们可以补充错误代码和消息，提供有关错误的更多具体信息。

API 终结点​

API 模块包含多个接口和可执行的操作。未来可能会添加更多接口和数据。于此处浏览 API 接口列表。

此接口文档根据 API 数据和代码注释生成，并将随时间推移不断扩充和更新。

上一页：配置设置