# HTTP API

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

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

# 接口安全

NanoMQ 的 HTTP API 使用 Basic 认证 (opens new window)JWT 认证 (opens new window)方式。usernamepassword 须分别填写。 默认的usernamepassword 是:admin/public。 可通过 etc/nanomq.conf 配置文件修改 usernamepassword

# 响应码

# HTTP 状态码 (status codes)

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

可能的状态码如下:

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

# 返回码 (result codes)

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

可能的返回码如下:

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

# API Endpoints | POST /api/v1

# NanoMQ 统计信息

返回 NanoMQ 的统计信息.

Parameters (json):

NameTypeRequiredValueDescription
reqIntegerRequired2请求码 2
seqIntegerRequireduniqueseq 是全局唯一的,请求/响应信息都会携带该信息,可以通过该值确定对应的请求响应。

Success Response Body (JSON):

NameTypeDescription
codeInteger0
seqIntegerseq 是全局唯一的,请求/响应信息都会携带该信息,可以通过该值确定对应的请求响应。
repIntegerrep 是 2 作为 req 2 的响应。
data.client_sizeInteger订阅客户端的数量。
data.message_inIntegerNanoMQ 流入的消息数量。
data.message_outIntegerNanoMQ 流出的消息数量。
data.message_dropIntegerNanoMQ 丢弃的消息数量。

# Examples:

$ 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}}
1
2

# 主题信息

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

Parameters (json):

NameTypeRequiredValueDescription
reqIntegerRequired4请求码 4
seqIntegerRequireduniqueseq 是全局唯一的,请求/响应信息都会携带该信息,可以通过该值确定对应的请求响应。

Success Response Body (JSON):

NameTypeDescription
codeInteger0
seqIntegerseq 是全局唯一的,请求/响应信息都会携带该信息,可以通过该值确定对应的请求响应。
repIntegerrep 是 4 作为 req 4 的响应。
data[0].client_idString客户端订阅标识符。
data[0].subscriptions[0].topicString订阅的主题。
data[0].subscriptions[0].qosInteger订阅的 qos

# Examples:

$ 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}]}]}
1
2

# 客户端信息

返回所有的客户端信息。

Parameters (json):

NameTypeRequiredValueDescription
reqIntegerRequired5请求码 5
seqIntegerRequireduniqueseq 是全局唯一的,请求/响应信息都会携带该信息,可以通过该值确定对应的请求响应。

Success Response Body (JSON):

NameTypeDescription
codeInteger0
seqIntegerseq 是全局唯一的,请求/响应信息都会携带该信息,可以通过该值确定对应的请求响应。
repIntegerrep 是 5 作为 req 5 的响应。
data[0].client_idString客户端订阅标识符。
data[0].usernameString用户名。
data[0].keepaliveInteger保活。
data[0].protocolInteger协议版本。
data[0].connect_statusInteger连接状态。
data[0].message_receiveInteger该客户端接受的消息。

# Examples:

$ 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}]
1
2

# 获取当前配置

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

Parameters (json):

NameTypeRequiredValueDescription
reqIntegerRequired11请求码 11
seqIntegerRequireduniqueseq 是全局唯一的,请求/响应信息都会携带该信息,可以通过该值确定对应的请求响应。

Success Response Body (JSON):

NameTypeDescription
codeInteger0
seqIntegerseq 是全局唯一的,请求/响应信息都会携带该信息,可以通过该值确定对应的请求响应。
repIntegerrep 是 11 作为 req 11 的响应。
data.urlString监听url。
data.num_taskq_threadInteger任务线程数。
data.max_taskq_threadInteger最大任务线程数。
data.parallelLong并行数。
data.property_sizeInteger最大属性长度。
data.msq_lenInteger队列长度。
data.qos_durationIntegerQOS消息定时间隔时间。
data.allow_anonymousBoolean允许匿名登录。
data.tls.enableBoolean启动TLS监听。
data.tls.urlStringTLS监听URL。
data.tls.keyStringTLS私钥数据。
data.tls.keypassStringTLS私钥密码。
data.tls.certStringTLS Cert证书数据。
data.tls.cacertStringTLS CA证书数据。
data.tls.verify_peerBoolean验证客户端证书
data.tls.fail_if_no_peer_certBoolean拒绝无证书连接,与_.tls.verify_peer_配合使用。
data.websocket.enableBoolean启动websocket监听。
data.websocket.urlStringWebsocket监听URL。
data.websocket.tls_urlStringTLS over Websocket监听URL。
data.http_server.enableBoolean启动Http服务监听。
data.http_server.portIntegerHttp服务端监听端口。
data.http_server.usernameString访问Http服务用户名。
data.http_server.passwordString访问Http服务密码。
data.bridge.bridge_modeBoolean启动桥接功能。
data.bridge.addressString桥接目标broker地址。
data.bridge.proto_verString桥接客户端MQTT版本(3|4|5)。
data.bridge.clientidString桥接客户端ID。(NULL为自动生成随机ID)
data.bridge.keepaliveInteger保活间隔时间。
data.bridge.clean_startBoolean清除会话。
data.bridge.parallelLong桥接客户端并发数。
data.bridge.usernameString登录用户名。
data.bridge.passwordString登录密码。
data.bridge.forwardsArray[String]转发Topic数组。
data.bridge.forwards[0]String转发Topic。
data.bridge.subscriptionArray[Object]订阅信息数组。
data.bridge.subscription[0].topicString订阅Topic。
data.bridge.subscription[0].qosInteger订阅消息质量Qos。

Example:

$ 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
                }
            ]
        }
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

# 设置配置参数

设置broker配置参数。

Parameters (json):

NameTypeRequiredValueDescription
reqIntegerRequired12请求码 12
seqIntegerRequireduniqueseq 是全局唯一的,请求/响应信息都会携带该信息,可以通过该值确定对应的请求响应。
dataObjectRequired同获取配置一致data

Success Response Body (JSON):

NameTypeDescription
codeInteger0
seqIntegerseq 是全局唯一的,请求/响应信息都会携带该信息,可以通过该值确定对应的请求响应。
repIntegerrep 是 12 作为 req 12 的响应。

Example:

$ 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}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65