HTTP API (V1)

NanoMQ 提供了 HTTP API 以实现与外部系统的集成，例如查询 broker 统计信息、客户端信息、发布消息，订阅主题信息和远程修改配置/重启等。

NanoMQ 的 HTTP API 服务默认监听 8081 端口。可通过 etc/nanomq.conf 配置文件修改监听端口，所有 API 调用均以 api/v1 开头。

接口安全

NanoMQ 的 HTTP API 使用 Basic 认证或 JWT 认证方式。username 和 password 须分别填写。默认的username 和 password 是：admin/public。可通过 etc/nanomq.conf 配置文件修改 username 和 password 。

响应码

HTTP 状态码 (status codes)

NanoMQ 接口在调用成功时总是返回 200 OK ，响应内容则以 JSON 格式返回。

可能的状态码如下：

Status Code	Description
200	成功，返回的 JSON 数据将提供更多信息
400	客户端请求无效，例如请求体或参数错误
401	客户端未通过服务端认证，使用无效的身份验证凭据可能会发生
404	找不到请求的路径或者请求的对象不存在
500	服务端处理请求时发生内部错误

返回码 (result codes)

NanoMQ 接口的响应消息体为 JSON 格式，其中总是包含返回码 code。

可能的返回码如下：

Return Code	Description
0	成功
101	RPC 错误
102	未知错误
103	用户名或密码错误
104	空用户名或密码
105	用户不存在
106	管理员账户不可删除
107	关键请求参数缺失
108	请求参数错误
109	请求参数不是合法 JSON 格式
110	插件已开启
111	插件已关闭
112	客户端不在线
113	用户已存在
114	旧密码错误
115	不合法的主题
116	Token 已过期

API Endpoints | POST /api/v1

NanoMQ 统计信息

返回 NanoMQ 的统计信息 .

Parameters (json):

Name	Type	Required	Value	Description
req	Integer	Required	2	请求码 2。
seq	Integer	Required	unique	seq 是全局唯一的，请求/响应信息都会携带该信息，可以通过该值确定对应的请求响应。

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
seq	Integer	seq 是全局唯一的，请求/响应信息都会携带该信息，可以通过该值确定对应的请求响应。
rep	Integer	rep 是 2 作为 req 2 的响应。
data.client_size	Integer	订阅客户端的数量。
data.message_in	Integer	NanoMQ 流入的消息数量。
data.message_out	Integer	NanoMQ 流出的消息数量。
data.message_drop	Integer	NanoMQ 丢弃的消息数量。

Examples:

shell

$ curl -i --basic -u admin:public -X POST "http://localhost:8081/api/v1" -d '{"req": 2,"seq": 1111111}'
{"code":0,"seq":1111111,"rep":2,"data":{"client_size":1,"message_in":4,"message_out":0,"message_drop":4}}

主题信息

返回客户端标识符对应的主题和 qos 信息。

Parameters (json):

Name	Type	Required	Value	Description
req	Integer	Required	4	请求码 4。
seq	Integer	Required	unique	seq 是全局唯一的，请求/响应信息都会携带该信息，可以通过该值确定对应的请求响应。

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
seq	Integer	seq 是全局唯一的，请求/响应信息都会携带该信息，可以通过该值确定对应的请求响应。
rep	Integer	rep 是 4 作为 req 4 的响应。
data[0].client_id	String	客户端订阅标识符。
data[0].subscriptions[0].topic	String	订阅的主题。
data[0].subscriptions[0].qos	Integer	订阅的 qos

Examples:

shell

$ curl -i --basic -u admin:public -X POST "http://localhost:8081/api/v1" -d '{"req": 4,"seq": 1111111}'
{"code":0,"seq":1111111,"rep":4,"data":[{"client_id":"nanomq-ebd54382","subscriptions":[{"topic":"a/b/c","qos":0}]}]}

客户端信息

返回所有的客户端信息。

Parameters (json):

Name	Type	Required	Value	Description
req	Integer	Required	5	请求码 5。
seq	Integer	Required	unique	seq 是全局唯一的，请求/响应信息都会携带该信息，可以通过该值确定对应的请求响应。

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
seq	Integer	seq 是全局唯一的，请求/响应信息都会携带该信息，可以通过该值确定对应的请求响应。
rep	Integer	rep 是 5 作为 req 5 的响应。
data[0].client_id	String	客户端订阅标识符。
data[0].username	String	用户名。
data[0].keepalive	Integer	保活。
data[0].protocol	Integer	协议版本。
data[0].connect_status	Integer	连接状态。
data[0].message_receive	Integer	该客户端接受的消息。

Examples:

shell

$ curl -i --basic -u admin:public -X POST "http://localhost:8081/api/v1" -d '{"req": 5,"seq": 1111111}'
{"code":0,"seq":1111111,"rep":5,"data":[{"client_id":"nanomq-ebd54382","username":"nanmq","keepalive":60,"protocol":4,"connect_status":1,"message_receive":0}]

获取当前配置

返回当前 broker 所有配置参数。

Parameters (json):

Name	Type	Required	Value	Description
req	Integer	Required	11	请求码 11。
seq	Integer	Required	unique	seq 是全局唯一的，请求/响应信息都会携带该信息，可以通过该值确定对应的请求响应。

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
seq	Integer	seq 是全局唯一的，请求/响应信息都会携带该信息，可以通过该值确定对应的请求响应。
rep	Integer	rep 是 11 作为 req 11 的响应。
data.url	String	监听 url 。
data.num_taskq_thread	Unsigned Integar 32 (Long)	任务线程数。
data.max_taskq_thread	Unsigned Integar 32 (Long)	最大任务线程数。
data.parallel	Unsigned Integar 32 (Long)	并行数。
data.property_size	Integer	最大属性长度。
data.msq_len	Integer	队列长度。
data.qos_duration	Integer	QOS 消息定时间隔时间。
data.allow_anonymous	Boolean	允许匿名登录。
data.tls.enable	Boolean	启动 TLS 监听。
data.tls.url	String	TLS 监听 URL 。
data.tls.key	String	TLS 私钥数据。
data.tls.keypass	String	TLS 私钥密码。
data.tls.cert	String	TLS Cert 证书数据。
data.tls.cacert	String	TLS CA 证书数据。
data.tls.verify_peer	Boolean	验证客户端证书
data.tls.fail_if_no_peer_cert	Boolean	拒绝无证书连接，与_.tls.verify_peer_配合使用。
data.websocket.enable	Boolean	启动 websocket 监听。
data.websocket.url	String	Websocket 监听 URL 。
data.websocket.tls_url	String	TLS over Websocket 监听 URL 。
data.http_server.enable	Boolean	启动 Http 服务监听。
data.http_server.port	Integer	Http 服务端监听端口。
data.http_server.username	String	访问 Http 服务用户名。
data.http_server.password	String	访问 Http 服务密码。
data.bridge.bridge_mode	Boolean	启动桥接功能。
data.bridge.address	String	桥接目标 broker 地址。
data.bridge.proto_ver	String	桥接客户端 MQTT 版本（ 3 ｜ 4 ｜ 5 ）。
data.bridge.clientid	String	桥接客户端 ID 。（ NULL 为自动生成随机 ID ）
data.bridge.keepalive	Integer	保活间隔时间。
data.bridge.clean_start	Boolean	清除会话。
data.bridge.parallel	Long	桥接客户端并发数。
data.bridge.username	String	登录用户名。
data.bridge.password	String	登录密码。
data.bridge.forwards	Array[String]	转发 Topic 数组。
data.bridge.forwards[0]	String	转发 Topic 。
data.bridge.subscription	Array[Object]	订阅信息数组。
data.bridge.subscription[0].topic	String	订阅 Topic 。
data.bridge.subscription[0].qos	Integer	订阅消息质量 Qos 。

Example:

shell

$ curl --location --request GET 'http://localhost:8081/api/v1' \
--header 'Authorization: Basic YWRtaW46cHVibGlj' \
--header 'Content-Type: application/json' \
--data-raw '{
    "req": 11,
    "seq": 9999
}'
{
    "code": 0,
    "seq": 9999,
    "rep": 11,
    "data": {
        "url": "nmq-tcp://0.0.0.0:1883",
        "num_taskq_thread": 4,
        "max_taskq_thread": 4,
        "parallel": 32,
        "property_size": 32,
        "msq_len": 64,
        "allow_anonymous": true,
        "daemon": false,
        "tls": {
            "enable": false,
            "url": "tls+nmq-tcp://0.0.0.0:8883",
            "key_password": null,
            "key": null,
            "cert": null,
            "cacert": null,
            "verify_peer": false,
            "fail_if_no_peer_cert": false
        },
        "websocket": {
            "enable": true,
            "url": "nmq-ws://0.0.0.0:8083/mqtt",
            "tls_url": "nmq-wss://0.0.0.0:8084/mqtt"
        },
        "http_server": {
            "enable": true,
            "port": 8081,
            "username": "admin",
            "password": "public",
            "auth_type": "basic"
        },
        "bridge": {
            "bridge_mode": false,
            "address": "mqtt-tcp://broker.emqx.io:1883",
            "proto_ver": 4,
            "clientid": "bridge_client",
            "clean_start": true,
            "username": "username",
            "password": "passwd",
            "keepalive": 60,
            "parallel": 2,
            "forwards": [
                "topic1/#",
                "topic2/#"
            ],
            "subscription": [
                {
                    "topic": "cmd/topic1",
                    "qos": 1
                },
                {
                    "topic": "cmd/topic2",
                    "qos": 2
                }
            ]
        }
    }
}

设置配置参数

设置 broker 配置参数。

Parameters (json):

Name	Type	Required	Value	Description
req	Integer	Required	12	请求码 12。
seq	Integer	Required	unique	seq 是全局唯一的，请求/响应信息都会携带该信息，可以通过该值确定对应的请求响应。
data	Object	Required		同获取配置一致data。

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
seq	Integer	seq 是全局唯一的，请求/响应信息都会携带该信息，可以通过该值确定对应的请求响应。
rep	Integer	rep 是 12 作为 req 12 的响应。

Example:

shell

$ curl --location --request POST 'http://localhost:8081/api/v1' \
--header 'Authorization: Basic YWRtaW46cHVibGlj' \
--header 'Content-Type: application/json' \
--data-raw '{
    "req": 12,
    "seq": 111,
    "data": {
        "url": "nmq-tcp://0.0.0.0:1883",
        "num_taskq_thread": 10,
        "max_taskq_thread": 10,
        "parallel": 10,
        "property_size": 32,
        "msq_len": 64,
        "allow_anonymous": true,
        "daemon": false,
        "tls": {
            "enable": false,
            "url": "tls+nmq-tcp://0.0.0.0:8883",
            "key_password": null,
            "key": null,
            "cert": null,
            "cacert": null,
            "verify_peer": false,
            "fail_if_no_peer_cert": false
        },
        "websocket": {
            "enable": true,
            "url": "nmq-ws://0.0.0.0:8083/mqtt",
            "tls_url": "nmq-wss://0.0.0.0:8084/mqtt"
        },
        "http_server": {
            "enable": true,
            "port": 8081,
            "username": "admin",
            "password": "public"
        },
        "bridge": {
            "bridge_mode": true,
            "address": "mqtt-tcp://broker.emqx.io:1883",
            "proto_ver": 4,
            "clientid": "bridge_client",
            "clean_start": true,
            "username": "username",
            "password": "passwd",
            "keepalive": 60,
            "parallel": 2,
            "forwards": [
                "topic1/#",
                "topic2/#"
            ],
            "subscription": [
                {
                    "topic": "cmd/topic1",
                    "qos": 1
                },
                {
                    "topic": "cmd/topic2",
                    "qos": 2
                }
            ]
        }
    }
}'

{"code":0,"seq":111,"rep":12}

HTTP API (V1) ​

接口安全 ​

响应码 ​

HTTP 状态码 (status codes) ​

返回码 (result codes) ​

API Endpoints | POST /api/v1 ​

NanoMQ 统计信息 ​

Examples: ​

主题信息 ​

Examples: ​

客户端信息 ​

Examples: ​

获取当前配置 ​

设置配置参数 ​

HTTP API (V1)

接口安全

响应码

HTTP 状态码 (status codes)

返回码 (result codes)

API Endpoints | POST /api/v1

NanoMQ 统计信息

Examples:

主题信息

Examples:

客户端信息

Examples:

获取当前配置

设置配置参数