详情代码请看：https://gitee.com/Discuz/discuz-restful-api

Discuz! RESTful API

文件说明

discuz_restful_sample.xml: RESTful API XML 文件范例
discuz_restful_official_trial.xml: 官方提供的范例接口，完整接口请通过管理中心“站长”>“RESTful 接口”的“导入接口”中在线安装“Discuz! Team”的接口，API 文档见 https://docs.apipost.net/docs/detail/2c7d89151864000
request_sample.php: PHP 版本的接口调用范例，其他语言范例参考 https://gitee.com/Discuz/UCenter/tree/master/developer （Discuz! RESTful API 规范和 UCenter 2.0 的 RESTful API 是一致的）

介绍

本手册所述内容目前仅针对 Discuz!ᵂ、Discuz! 企飞版，Discuz! X5。 RESTful API 为 Discuz! 基于 oAuth2 协议开发的一套开放的 API 接口。正常情况下，您只需要书写一个 XML 文件即可创建一个 API 接口，而无需书写 PHP 代码。本 Git 附带的 discuz_restful_official_trial.xml 文件为范例文件，您可以打开阅读协助您开发出自己的 API。

XML 规范

此 XML 遵从 Discuz! 标准的开放 XML 格式书写方法。

<?xml version="1.0" encoding="ISO-8859-1"?>
<root>
    <item id="Title"><![CDATA[Discuz! RESTful]]></item>
    <item id="Data">
        <item id="copyright"><![CDATA[Discuz! Team]]></item>
        <item id="api">
            <item id="v1">
            ......
            </item>
        </item>
    </item>
</item>        

主体结构

Title 节点为固定内容“Discuz! RESTful”，识别 XML 内容类型
Data 节点为具体接口数据
Data.copyright 为版权信息，您可以写上您的姓名
Data.api 为详细的 API 列表及内容

Data.api

在 Data.api 节点中，必须首先声明版本号，我们本着多版本兼容共存的原则，我们建议您在开发 API 的时候旧版本定型稳定后请不要再去改动它，而是启用新版本号。用户在 Discuz! 管理中心导入的时候，多版本是可以同时存在的。

<item id="v1">
......
</item>
<item id="v2">
......
</item>
......

接口声明

一个接口需完成以下内容的声明才能生效

<item id="接口path">
    <item id="name"><![CDATA[接口名称]]></item>
    <item id="attr">
        <item id="validateData"><![CDATA[1]]></item>
        <item id="validateUnique"><![CDATA[30]]></item>
    </item>
    <item id="script"><![CDATA[调用脚本]]></item>
    <item id="output">
        ...... 输出变量映射
    </item>
    <item id="plugin">
        ...... 过滤插件
    </item>
    <item id="get">
        ...... GET 参数
    </item>
    <item id="post">
        ...... POST 参数
    </item>
    <item id="usage">
        ...... 参数说明
    </item>
</item>

接口path

英文字母、数字、下划线的组合，如：forumdisplay，那么这个接口的具体 URL 为 /api/restful?/forumdisplay 如接口要分级，请按照如下方式书写，可定义出 /api/restful?/member/loginInfo、/api/restful?/member/registerInfo 2个用户接口

<item id="member">
    <item id="name"><![CDATA[用户接口]]></item>
    <item id="loginInfo">
        ......
    </item>
    <item id="registerInfo">
        ......
    </item>
</item>    

调用脚本

当前接口调用的脚本名，如调用 forum.php，填写 forum，只能填写根目录的脚本

输出变量映射

输出映射按照如下规则填写多条

<item id="output">
    <item id="原变量"><![CDATA[映射KEY]]></item>
    ......
</item>

例如：

<item id="output">
    <item id="_G/dshowmessageParam"><![CDATA[msg]]></item>
    <item id="_G/uid,username,groupid,groupname"><![CDATA[user]]></item>
    <item id="_L/seccodecheck"><![CDATA[seccodecheck]]></item>
</item>

_G/dshowmessageParam 表示把 $_G[‘dshowmessageParam’] 变量的内容映射到 API json 中 “msg” 这个 key 的内容中
_G/uid,username,groupid,groupname 表示把 $_G 的 uid、username、groupid、groupname 4个 key 的内容映射到 “user” 中
_L/seccodecheck 把，局部变量（通常在 class、function 内部）$seccodecheck 的内容，映射到 “seccodecheck” 中

GET、POST 参数

GET、POST 为指定调用脚本具体的参数，例如

<item id="get">
    <item id="mod"><![CDATA[logging]]></item>
    <item id="action"><![CDATA[login]]></item>
    <item id="loginsubmit"><![CDATA[yes]]></item>
</item>
<item id="post">
    <item id="fastloginfield"><![CDATA[username]]></item>
    <item id="username"><![CDATA[{:username:}]]></item>
    <item id="password"><![CDATA[{:password:}]]></item>
    <item id="formhash"><![CDATA[{:formhash:}]]></item>
</item>

当 value 为 "{:xxx:}" 格式的时候，xxx 的内容为当前 API 接口的参数，需要调用方进行传参 {:formhash:} 为系统参数，调用方无需额外传参

参数说明

参数说明非必须，当您定义了多个 API 接口参数的时候，书写此说明文本，可以在 Discuz! 管理中心生成一个简单的接口说明文档

<item id="usage">
    <item id="username"><![CDATA[用户名]]></item>
    <item id="password"><![CDATA[密码]]></item>
</item>

接口属性

validateData: 值为 1，有此属性时，表示调用接口需要验证数据的完整性。请求时需要在 Header 中发送 validatecode 字段，此字段的值为校验码，校验码算法如下，其中 $post 为 json 后的参数

sha1($secret.$post)

validateUnique: 有此属性时，表示调用接口需要验证唯一性，值传递唯一性值的有效期。请求时需要在 Header 中发送 uniqueid 字段，此字段的值为唯一串

包含以上属性接口的请求方法可参考范例中的 _request() 方法

过滤插件

过滤插件可以通过脚本对输出的数据进行额外的处理

<item id="plugin">
    <item id="before">
        <item id="函数">
            <item id="param"><![CDATA[参数]]></item>
        </item>
        .....
    </item>
    <item id="after">
        <item id="函数">
            <item id="param"><![CDATA[参数]]></item>
        </item>
        ......
    </item>
</item>

插件分为 before、after 2类，before 会在调用脚本执行前被调用，after 会在脚本执行完毕后被调用插件脚本的固定路径为 “source/plugin/pluginid/restful.class.php”，考虑到 before 会在调用脚本执行前被调用的缘故，此脚本可以不书写 “defined(‘IN_DISCUZ’)” 的判断 restful.class.php 是一个 class，您需要书写一个以下内容的脚本

<?php

class restful_pluginid {

    // pluginid:beforePlugin
    public static function beforePlugin(&$data, $param) {
        
    }

    // pluginid:afterPlugin
    public static function afterPlugin(&$data, $param) {
        
    }    

}

对于以上 2 个方法，函数填写的内容为 "pluginid:beforePlugin"、"pluginid:afterPlugin"

param 节点为函数参数，多个参数用逗号”,“分隔，param 的内容会传递给相应的静态方法，脚本中只需修改 $data 的内容即可对相应输出变量进行处理，例如

<item id="plugin">
    <item id="after">
        <item id="pluginid:thread">
            <item id="param"><![CDATA[forum_thread]]></item>
        </item>
    </item>
</item>

class restful_pluginid {

    // pluginid:thread
    public static function thread(&$data, $param) {
        global $_G;

        $key = $param[0];
        if(empty($data[$key])) {
            return;
        }

        //接口隐藏匿名
        if($data[$key]['authorid'] > 0 && $data[$key]['author'] === '') {
            $data[$key]['author'] = $_G['setting']['anonymoustext'];
            $data[$key]['authorid'] = 0;
        }
    }

}

可参考插件范例：https://gitee.com/Discuz/DiscuzXPluginSample/tree/DZW

XML 的导入和更新

XML 写好后你可以用分享的形式将 XML 发布出去，用户在 “Discuz! 管理中心 > 站长 > RESTful 接口” 导入即可使用，多次导入会覆盖、更新旧版本。

添加更新源

您可以自己设计一个更新源的接口，接口直接吐出 XML 内容。然后，要让更新源生效，您可以在兼容 W1.0 版插件的安装脚本中补充以下 SQL。

INSERT INTO pre_restful_source (name, url) VALUES ('My Team', 'http://youapiurl');

接口的调用

使用前需要先创建一个应用，获取 appid 和 secret，并设置好权限。

全局参数

全局参数包含 4 个 appid、nonce、t、sign，请将此 4 个参数添加到请求的 Header 中 nonce 为唯一串，请保证唯一性，可用 uuid t 为时间戳 sign 为签名，下面提供 2 个版本的签名算法

$sign = base64_encode(hash('sha256', $nonce.$t.$secret));
function getSign(nonce, t, secret) {
    let sha256 = CryptoJS.SHA256(nonce + t + secret).toString();
    let base64_sign = CryptoJS.enc.Base64.stringify(CryptoJS.enc.Utf8.parse(sha256));
    return base64_sign;
}

接口的请求

请求范例见 request_sample.php。所有的接口参数都请通过 POST 提交。 “_REQUEST” 是通用接口参数的名称，如接口参数未涉及到原脚本某些请求参数时，可用此通用参数，此参数为 json 字串，为以下格式：

{
    "GET": {
        "key": "value",
        ......
    },
    "POST": {
        "key": "value",
        ......
    },
    "COOKIE": {
        "key": "value",
        ......
    },
}

不涉及相关类型的请求参数时可忽略，比如不包含 POST、COOKIE 时可留空

获取 Token

在获取所有其他接口前，您需要先获取 Token，Token 接口URL：/api/restful/?/token 请求参数：

token: (可选)刷新 Token 时携带旧的 Token

返回参数：

{
    "ret": 0,
    "token": "LUIXE1DWBGQIQDSU",
    "expires_in": 1703911668
}

返回 token 和有效期，业务方可自行判断

其他接口

获取到 Token 后，您可以把 Token 放入请求的 Header 中，也可以作为正常的全局参数带入，变量名为 “token” 具体接口的请求参数和返回参数视具体接口定义而定

restful 类常量说明

在 X5 的 class_restful.php 中有以下 2 个常量，可酌情进行调整

const RESTFUL_REDIS_PREFIX = '';
const RESTFUL_DEVELOPER_MODE = false;

RESTFUL_REDIS_PREFIX:

Discuz! RESTful 默认使用 Redis 存储 API 数据，默认只支持一个站点，如果存在多个站点公用同一个 Redis 的情况，请在此处填写多个站的代号，避免 Redis key 冲突

RESTFUL_DEVELOPER_MODE

为了方便开发者本地开发自己的 API 接口，本地开发 API 时可以设置为 true。开发者只需调试 data/discuz_restful.xml 文件，而无需反复在管理中心导入接口

开发文档

参考资源

X5特性介绍

RESTful API 开发手册

Discuz! RESTful API

文件说明

介绍

XML 规范

主体结构

Data.api

接口声明

接口path

调用脚本

输出变量映射

GET、POST 参数

参数说明

接口属性

过滤插件

XML 的导入和更新

添加更新源

接口的调用

全局参数

接口的请求

获取 Token

其他接口

restful 类常量说明

RESTFUL_REDIS_PREFIX:

RESTFUL_DEVELOPER_MODE

​Discuz! RESTful API

​文件说明

​介绍

​XML 规范

​主体结构

​Data.api

​接口声明

接口path

调用脚本

输出变量映射

GET、POST 参数

参数说明

接口属性

过滤插件

​XML 的导入和更新

​添加更新源

​接口的调用

​全局参数

​接口的请求

​获取 Token

​其他接口

​restful 类常量说明

RESTFUL_REDIS_PREFIX:

RESTFUL_DEVELOPER_MODE

Discuz! RESTful API

文件说明

介绍

XML 规范

主体结构

Data.api

接口声明

XML 的导入和更新

添加更新源

接口的调用

全局参数

接口的请求

获取 Token

其他接口

restful 类常量说明