Skip to content

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 访问：

src/config.php
$config['enableApi'] = false;

API 密钥#

API 密钥通过管理后台的 设置 > API 密钥 创建。由于生成 API 密钥可能允许访问高权限数据，仅超级管理员可进入此系统。每当生成 API 密钥时，所有超级管理员都会收到邮件通知以确保请求合法性。

创建密钥时将生成随机字符串，该字符串用于 API 身份验证。请务必妥善保管此密钥。若怀疑密钥已泄露，请立即重新生成密钥并更新使用旧密钥的所有代码。

密钥类型#

所有 API 访问均在特定用户上下文环境中执行。例如，若以"John"身份访问 API 并执行发帖请求，该主题将显示由"John"创建。多数情况下，API 也将遵循该用户的权限设置，确保其无法访问在正常浏览论坛时不可见的数据。

为此，API 密钥分为三种类型：

  • 游客密钥 - 始终以游客身份访问 API。这类请求始终遵循游客权限。例如，若游客无法回复主题，则通过此密钥发送的回帖请求将返回无权限错误。
  • 用户密钥 - 始终以指定用户身份访问 API，并始终遵循该用户权限，类似游客密钥。
  • 超级用户密钥 - 可通过传递附加参数以任意用户身份访问 API。可选地，此类密钥可绕过请求用户的权限限制，允许其执行超出常规权限的操作或查看受限内容。

超级用户密钥在系统集成场景中非常实用。例如，当与第三方 CMS 集成实现"发布新文章时自动创建主题"功能时，使用此类密钥可根据文章作者选择不同用户身份发帖，或在普通用户无发帖权限的版块中创建主题。

密钥作用域#

为限制泄露密钥可能造成的损害，每个密钥可控制其可访问的 API 作用域。作用域独立于请求用户权限，用于限制 API 功能模块的访问权限。

API 中的每个端点都关联一个或多个作用域。若密钥未获得任一关联作用域授权，请求将失败。

出于安全考虑，建议仅授予密钥所需的作用域权限。后续如需扩展权限，可随时添加。

访问 API#

在确认 API 访问地址并获取密钥后，即可开始发送请求。

除明确请求二进制文件（如下载附件）的情况外，所有 API 响应均以 JSON 格式返回。错误响应将返回 400 系列状态码，成功请求返回 200 状态码。较少情况下可能返回 300 系列重定向状态码。

请求体需使用 application/x-www-form-urlencoded 编码，上传文件时需使用 multipart/form-data 编码。参数也可通过查询字符串传递，但对于非 GET 请求，强烈建议通过请求体传递参数。

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

所有请求需通过 XF-Api-Key 请求头传递 API 密钥，该头信息必须存在于所有请求中。

若使用超级用户密钥，可通过 XF-Api-User 请求头传递上下文用户的用户 ID。未传递时默认使用游客身份。

使用超级用户密钥发送请求时，若希望绕过上下文用户的权限限制，可通过设置 api_bypass_permissions 参数为 1 实现（可通过查询字符串或请求体传递）。

错误处理#

出现错误时响应码为 400 系列。偶发 500 系列错误表示服务器无法处理请求，可能因 API 暂时禁用或其他服务器错误导致。

错误信息采用标准格式，示例如下：

错误响应
{
    "errors": [
        {
            "code": "api_key_not_found",
            "message": "请求中提供的 API 密钥不存在",
            "params": []
        }
    ]
}

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

  • code - 机器可读的错误代码，具体代码取决于错误场景
  • message - 人类可读的错误描述，内容可能变动或本地化，不建议用于错误类型识别
  • params - 与错误相关的键值参数列表，可补充说明错误细节

API 端点#

API 包含多个可操作的端点。未来可能新增更多端点与数据支持。

查看 API 端点文档

该端点文档根据代码中的 API 数据与注释生成，将持续更新完善。