# HTTP API (V4)

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

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

访问旧版本 HTTP 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

# GET /api/v4

返回 NanoMQ 支持的所有 Endpoints。

Parameters:

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArrayEndpoints 列表
- data[0].pathStringEndpoint
- data[0].nameStringEndpoint 名
- data[0].methodStringHTTP Method
- data[0].descrString描述

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4"

{"code":0,"data":[{"path":"/brokers/","name":"list_brokers","method":"GET","descr":"A list of brokers in the cluster"},{"path":"/nodes/","name":"list_nodes","method":"GET","descr":"A list of nodes in the cluster"},{"path":"/clients/","name":"list_clients","method":"GET","descr":"A list of clients on current node"},{"path":"/clients/:clientid","name":"lookup_client","method":"GET","descr":"Lookup a client in the cluster"},{"path":"/clients/username/:username","name":"lookup_client_via_username","method":"GET","descr":"Lookup a client via username in the cluster"},{"path":"/subscriptions/","name":"list_subscriptions","method":"GET","descr":"A list of subscriptions in the cluster"},{"path":"/subscriptions/:clientid","name":"lookup_client_subscriptions","method":"GET","descr":"A list of subscriptions of a client"},{"path":"/topic-tree/","name":"list_topic-tree","method":"GET","descr":"A list of topic-tree in the cluster"},{"path":"/configuration/","name":"get_broker_configuration","method":"GET","descr":"show broker configuration"},{"path":"/configuration/","name":"set_broker_configuration","method":"POST","descr":"set broker configuration"},{"path":"/ctrl/:action","name":"ctrl_broker","method":"POST","descr":"Control broker stop or restart"}]}
1
2
3

# Broker 基本信息

# GET /api/v4/brokers

返回Broker的基本信息。

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataObject/Array of Objects返回所有节点的信息*(只有一个节点,nanomq暂不支持集群)*
data.datetimeString当前时间,格式为 "YYYY-MM-DD HH:mm:ss"
data.node_statusString节点状态
data.sysdescrString软件描述
data.uptimeStringNanoMQ运行时间,格式为 "H hours, m minutes, s seconds"
data.versionStringNanoMQ 版本
$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/brokers"

{"code":0,"data":[{"datetime":"2022-06-07 10:02:24","node_status":"Running","sysdescr":"NanoMQ Broker","uptime":"15 Hours, 1 minutes, 38 seconds","version":"0.7.9-3"}]}
1
2
3

# 节点

# GET /api/v4/nodes

返回节点的状态。

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataObject/Array of Objects以 Array 形式返回所有节点的信息*(只有一个节点,nanomq暂不支持集群)*
data.connectionsInteger当前接入此节点的客户端数量
data.node_statusString节点状态
data.uptimeStringNanoMQ 运行时间
data.versionStringNanoMQ 版本

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/nodes"

{"code":0,"data":[{"connections":0,"node_status":"Running","uptime":"15 Hours, 22 minutes, 4 seconds","version":"0.8.1"}]}
1
2
3

# 客户端

# GET /api/v4/clients

支持多条件查询,其包含的查询参数有:

NameTypeRequiredDescription
clientidStringFalse客户端标识符
usernameStringFalse客户端用户名
conn_stateEnumFalse客户端当前连接状态, 可取值有:connected,idle,disconnected
clean_startBoolFalse客户端是否使用了全新的会话
proto_nameEnumFalse客户端协议名称, 可取值有:MQTT,CoAP,LwM2M,MQTT-SN
proto_verIntegerFalse客户端协议版本

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of Objects所有客户端的信息
data[0].clientidString客户端标识符
data[0].usernameString客户端连接时使用的用户名
data[0].proto_nameString客户端协议名称 (MQTT,CoAP,LwM2M,MQTT-SN)
data[0].proto_verInteger客户端使用的协议版本
data[0].connectedBoolean客户端是否处于连接状态
data[0].keepaliveInteger保持连接时间,单位:秒
data[0].clean_startBoolean指示客户端是否使用了全新的会话
data[0].recv_msgInteger接收的 PUBLISH 报文数量

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/clients"

{"code":0,"data":[{"client_id":"nanomq-f6d6fbfb","username":"alvin","keepalive":60,"conn_state":"connected","clean_start":true,"proto_name":"MQTT","proto_ver":5,"recv_msg":3},{"client_id":"nanomq-bdf61d9b","username":"nanomq","keepalive":60,"conn_state":"connected","clean_start":true,"proto_name":"MQTT","proto_ver":5,"recv_msg":0}]}
1
2
3

# GET /api/v4/clients/{clientid}

返回指定客户端的信息

Path Parameters:

NameTypeRequiredDescription
clientidStringTrueClientID

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of Objects客户端的信息,详细请参见 [GET /api/v4/clients](#GET /api/v4/clients)

Examples:

查询指定客户端

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/clients/nanomq-29978ec1"

{"code":0,"data":[{"client_id":"nanomq-29978ec1","username":"","keepalive":60,"conn_state":"connected","clean_start":true,"proto_name":"MQTT","proto_ver":5}]}
1
2
3

# GET /api/v4/clients/username/{username}

通过 Username 查询客户端的信息。由于可能存在多个客户端使用相同的用户名的情况,所以可能同时返回多个客户端信息。

Path Parameters:

NameTypeRequiredDescription
usernameStringTrueUsername

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of Objects客户端的信息,详细请参见 [GET /api/v4/clients](#GET /api/v4/clients)

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/clients/username/user001"

{"code":0,"data":[{"client_id":"nanomq-56baa74d","username":"user001","keepalive":60,"conn_state":"connected","clean_start":true,"proto_name":"MQTT","proto_ver":5}]}
1
2
3

# 订阅信息

# GET /api/v4/subscriptions

支持多条件查询:

NameTypeDescription
clientidString客户端标识符
topicString主题,全等查询
qosEnum可取值为:0,1,2
shareString共享订阅的组名称

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of Objects所有订阅信息
data[0].clientidString客户端标识符
data[0].topicString订阅主题
data[0].qosIntegerQoS 等级

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/subscriptions"

{"code":0,"data":[{"clientid":"nanomq-29978ec1","topic":"topic123","qos":2},{"clientid":"nanomq-3020ffac","topic":"topic123","qos":2}]}
1
2
3

# GET /api/v4/subscriptions/{clientid}

返回指定客户端的订阅信息。

Path Parameters:

NameTypeRequiredDescription
clientidStringTrueClientID

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataObject所有订阅信息
data.clientidString客户端标识符
data.topicString订阅主题
data.qosIntegerQoS 等级

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/subscriptions/123"

{"data":[{"topic":"a/b/c","qos":1,"clientid":"123"}],"code":0}
1
2
3

# 消息发布

# POST /api/v4/mqtt/publish

发布 MQTT 消息。

Parameters (json):

NameTypeRequiredDefaultDescription
topicStringOptional主题,与 topics 至少指定其中之一
topicsStringOptional, 分割的多个主题,使用此字段能够同时发布消息到多个主题
clientidStringRequired客户端标识符
payloadStringRequired消息正文
encodingStringOptionalplain消息正文使用的编码方式,目前仅支持 plainbase64 两种
qosIntegerOptional0QoS 等级
retainBooleanOptionalfalse是否为保留消息
propertiesObjectOptional{}PUBLISH 消息里的 Property 字段

Properties取值:

NameTypeDescription|
payload_format_indicatorInteger载荷格式指示标识符,0说明载荷是未指定格式的字节,相当于没有发送载荷格式指示,说明载荷是 UTF-8 编码的字符数据。载荷中的 UTF-8 数据必须是按照 Unicode 的规范和 RFC 3629 的重申进行编码
message_expiry_intervalinteger消息过期间隔标识符,以秒为单位,如果已过期,服务端还没有开始向匹配的订阅者交付该消息时,则服务端必须删除该订阅者的消息副本,不设置,则消息不会过期。
response_topicString响应主题标识符, UTF-8 编码的字符串,用作响应消息的主题名,响应主题不能包含通配符,包含多个响应主题将造成协议错误(Protocol Error)。响应主题的存在将消息标识为请求报文。服务端在收到应用消息时必须将响应主题原封不动的发送给所有的订阅者。
correlation_dataString对比数据标识符,服务端在收到应用消息时必须原封不动的把对比数据发送给所有的订阅者。对比数据只对请求消息(Request Message)的发送端和响应消息(Response Message)的接收端有意义。
subscription_identifierInteger订阅标识符标识符,订阅标识符取值范围从 1 到 268,435,455。订阅标识符的值为 0 将造成协议错误。如果某条发布消息匹配了多个订阅,则将包含多个订阅标识符。这种情况下他们的顺序并不重要。
content_typeString内容类型标识符,以 UTF-8 格式编码的字符串,用来描述应用消息的内容,服务端必须把收到的应用消息中的内容类型原封不动的发送给所有的订阅者
user_propertiesObject用户属性(User Property)允许出现多次,以表示多个名字/值对,服务端在转发应用消息到客户端时必须原封不动的把所有的用户属性放在 PUBLISH 报文中

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

$ curl -i --basic -u admin:public -X POST "http://localhost:8081/api/v4/mqtt/publish" -d \
'{"topic":"a/b/c", "payload":"Hello World", "qos":1, "retain":false, "clientid":"example", "properties": {"user_properties": { "id": 10010, "name": "name", "foo": "bar"}, "content_type": "text/plain"}}'

{"code":0}
1
2
3
4

# 主题订阅

# POST /api/v4/mqtt/subscribe

订阅 MQTT 主题。

Parameters (json):

NameTypeRequiredDefaultDescription
topicStringOptional主题,与 topics 至少指定其中之一
topicsStringOptional, 分割的多个主题,使用此字段能够同时订阅多个主题
clientidStringRequired客户端标识符
qosIntegerOptional0QoS 等级

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

同时订阅 a, b, c 三个主题

$ curl -i --basic -u admin:public -X POST "http://localhost:8081/api/v4/mqtt/subscribe" -d '{"topics":"a,b,c","qos":1,"clientid":"example"}'

{"code":0}
1
2
3

# POST /api/v4/mqtt/unsubscribe

取消订阅。

Parameters (json):

NameTypeRequiredDefaultDescription
topicStringRequired主题
clientidStringRequired客户端标识符

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

取消订阅 a 主题

$ curl -i --basic -u admin:public -X POST "http://localhost:8081/api/v4/mqtt/unsubscribe" -d '{"topic":"a","qos":1,"clientid":"example"}'

{"code":0}
1
2
3

# 消息批量发布

# POST /api/v4/mqtt/publish_batch

批量发布 MQTT 消息。

Parameters (json):

NameTypeRequiredDefaultDescription
[0].topicStringOptional主题,与 topics 至少指定其中之一
[0].topicsStringOptional, 分割的多个主题,使用此字段能够同时发布消息到多个主题
[0].clientidStringRequired客户端标识符
[0].payloadStringRequired消息正文
[0].encodingStringOptionalplain消息正文使用的编码方式,目前仅支持 plainbase64 两种
[0].qosIntegerOptional0QoS 等级
[0].retainBooleanOptionalfalse是否为保留消息
[0].propertiesObjectOptional{}PUBLISH 消息里的 properties 字段

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

$ curl -i --basic -u admin:public -X POST "http://localhost:8081/api/v4/mqtt/publish_batch" -d '[{"topic":"a/b/c","payload":"Hello World","qos":1,"retain":false,"clientid":"example","properties": {"user_properties":{"id": 10010, "name": "nanomq", "foo": "bar"}}},{"topic":"a/b/c","payload":"Hello World Again","qos":0,"retain":false,"clientid":"example","properties":{"user_properties": { "id": 10010, "name": "nanomq", "foo": "bar"},"content_type": "text/plain"}}]'

{"data":[{"topic":"a/b/c","code":0},{"topic":"a/b/c","code":0}],"code":0}
1
2
3

# 主题批量订阅

# POST /api/v4/mqtt/subscribe_batch

批量订阅 MQTT 主题。

Parameters (json):

NameTypeRequiredDefaultDescription
[0].topicStringOptional主题,与 topics 至少指定其中之一
[0].topicsStringOptional, 分割的多个主题,使用此字段能够同时订阅多个主题
[0].clientidStringRequired客户端标识符
[0].qosIntegerOptional0QoS 等级

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

一次性订阅 a, b, c 三个主题

$ curl -i --basic -u admin:public -X POST "http://localhost:8081/api/v4/mqtt/subscribe_batch" -d '[{"topic":"a","qos":1,"clientid":"example"},{"topic":"b","qos":1,"clientid":"example"},{"topic":"c","qos":1,"clientid":"example"}]'

{"code":0}
1
2
3

# POST /api/v4/mqtt/unsubscribe_batch

批量取消订阅。

Parameters (json):

NameTypeRequiredDefaultDescription
[0].topicStringRequired主题
[0].clientidStringRequired客户端标识符

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

一次性取消订阅 a, b 主题

$ curl -i --basic -u admin:public -X POST "http://localhost:8081/api/v4/mqtt/unsubscribe_batch" -d '[{"topic":"a","qos":1,"clientid":"example"},{"topic":"b","qos":1,"clientid":"example"}]'

{"code":0}
1
2
3

# 主题树结构

# GET /api/v4/topic-tree

Success Response Body (JSON):

NameTypeDescription
codeInteger0
dataArray of Objects所有订阅信息
data[0].clientidArray of String客户端标识符数组
data[0].topicString订阅主题
data[0].cld_cntInteger子节点个数

Examples:

$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/topic-tree"

{"code":0,"data":[[{"topic":"","cld_cnt":1}],[{"topic":"topic123","cld_cnt":1,"clientid":["nanomq-3a4a0956"]}],[{"topic":"123","cld_cnt":1,"clientid":["nanomq-0cfd69bb"]}],[{"topic":"456","cld_cnt":0,"clientid":["nanomq-26971dc8"]}]]}
1
2
3

# 获取热更新配置

# GET /api/v4/reload

返回当前所有支持热更新的配置参数。

Success Response Body (JSON):

NameTypeDescription
codeInteger0
data.property_sizeInteger最大属性长度。
data.msq_lenInteger队列长度。
data.qos_durationIntegerQOS消息定时间隔时间。
data.allow_anonymousBoolean允许匿名登录。
data.max_packet_sizeKbytesNanoMQ 的最大包大小 (Kbytes)
data.client_max_packet_sizeKbytes每个 client 的 最大包大小
data.keepalive_backoffIntegerMQTT keepalive 的退避指数

Examples:

$ curl -i --basic -u admin:public -X GET 'http://127.0.0.1:8081/api/v4/reload' 

{
    "code": 0,
    "data": {
        "property_size": 64,
        "max_packet_size": 3,
        "client_max_packet_size": 5,
        "msq_len": 2048,
        "qos_duration": 10,
        "keepalive_backoff": 1250,
        "allow_anonymous": false
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 设置热更新配置

# POST /api/v4/reload

设置热配置参数。

Parameters (json):

NameTypeRequiredValueDescription
dataObjectRequired同获取热更新配置一致 获取热更新配置

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

$ curl -i --basic -u admin:public -X POST 'http://localhost:8081/api/v4/configuration' -d \
'{
       "data": {
        "property_size": 64,
        "max_packet_size": 3,
        "client_max_packet_size": 5,
        "msq_len": 2048,
        "qos_duration": 10,
        "keepalive_backoff": 1250,
        "allow_anonymous": false
    }
}'

{"code":0}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# Broker控制

# POST /api/v4/ctrl/{action}

控制broker停止或重启(通常应用在修改配置后)

Path Parameters:

NameTypeRequiredDescription
clientidStringTrue可取值: stop, restart

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

$ curl -i --basic -u admin:public -X POST 'http://localhost:8081/api/v4/restart'

{"code":0}
1
2
3

# 规则

查询规则引擎的动作

# GET /api/v4/rules/

获取规则列表, 包括规则的 SQL, id 等。

Success Response Body (JSON):

NameTypeDescription
codeInteger0
enabledBoolean过滤条件:规则是否开启状态
dataArray of Objects规则详情
data[0].idString规则ID
data[0].rawsqlStringSQL 语句,与请求中的 rawsql 一致

# GET /api/v4/rules/{rule_id}

获取某个规则的详情, 包括规则的 SQL, id 等。 Path Parameters:

NameTypeRequiredDescription
rule_idStringFalse可选,Rule ID。如不指定 rule_id 则以数组形式返回所有已创建的规则

Success Response Body (JSON):

NameTypeDescription
codeInteger0
enabledBoolean过滤条件:规则是否开启状态
dataArray of Objects规则详情
- data.idString规则ID
- data.rawsqlStringSQL 语句,与请求中的 rawsql 一致

# POST /api/v4/rules

创建规则,返回规则 ID。

Parameters (json):

NameTypeRequiredDescription
rawsqlStringTrue规则的 SQL 语句
actionsArrayTrue动作列表
- actions[0].nameStringTrue动作名称 (include repub, mysql, sqlite)
- actions[0].paramsObjectTrue动作参数。参数以 key-value 形式表示。详情可参看添加规则的示例
descriptionStringFalse可选,规则描述

Success Response Body (JSON):

NameTypeDescription
codeInteger0
enabledBoolean过滤条件:规则是否开启状态
dataArray of Objects规则详情
- data.idString规则ID
- data.rawsqlStringSQL 语句,与请求中的 rawsql 一致

# PUT /api/v4/rules/{rule_id}

更新规则,返回规则 ID。

Parameters (json):

NameTypeRequiredDescription
rawsqlStringTrue可选,规则的 SQL 语句
actionsArrayTrue可选,动作列表
- actions[0].nameStringTrue可选,动作名称
- actions[0].paramsObjectTrue可选,动作参数。参数以 key-value 形式表示。详情可参看添加规则的示例
descriptionStringFalse可选,规则描述

Success Response Body (JSON):

NameTypeDescription
codeInteger0
enabledBoolean过滤条件:规则是否开启状态
dataArray of Objects规则详情
- data.idString规则ID
- data.rawsqlStringSQL 语句,与请求中的 rawsql 一致

# DELETE /api/v4/rules/{rule_id}

删除规则。

Parameters:

Success Response Body (JSON):

NameTypeDescription
codeInteger0

Examples:

添加一个规则,对于所有匹配到主题 "t/a" 的消息,打印其规则运行参数。

$ curl -XPOST -d '{
  "rawsql": "select * from \"t/a\"",
  "actions": [{
      "name": "repub",
      "params": {
          "topic": "repub1", "address":"broker.emqx.io:1883", "clean_start": "true", "clientid": "id", "username": "admin", "password": "public", "proto_ver": 4, "keepalive": 60
      }
  }],
  "description": "repub-rule"

}' --basic -u admin:public 'http://localhost:8081/api/v4/rules'

{"data":{"rawsql":"select * from \"t/a\"","id":4,"enabled":true},"actions":[],"code":0}
1
2
3
4
5
6
7
8
9
10
11
12
13

使用规则 ID 获取刚才创建的规则详情:

$ curl --basic -u admin:public 'http://localhost:8081/api/v4/rules/rule:4'

{"data":{"rawsql":"select * from \"t/a\"","id":1,"enabled":true},"actions":[],"code":0}
1
2
3

获取所有的规则,注意返回值里的 data 是个规则对象的数组:

$ curl --basic -u admin:public 'http://localhost:8081/api/v4/rules'

{"data":[{"rawsql":"SELECT payload.x.y as y, payload.z as z FROM \"#\" WHERE y > 10 and z != 'str'","id":1,"enabled":true},{"rawsql":"SELECT * FROM \"abc\"","id":2,"enabled":true},{"rawsql":"SELECT payload, qos FROM \"#\" WHERE qos > 0","id":3,"enabled":true},{"rawsql":"select * from \"t/a\"","id":4,"enabled":true}],"code":0}
1
2
3

更新一下规则的 SQL 语句,改为 select * from "t/b":

$ curl -XPUT --basic -u admin:public 'http://localhost:8081/api/v4/rules/rule:4' -d '{"rawsql":"select * from \"t/b\""}'

{"data":{"rawsql":"select * from \"t/b\"","id":4,"enabled":true},"actions":[],"code":0}
1
2
3

停用规则 (disable):

$ curl -XPUT --basic -u admin:public 'http://localhost:8081/api/v4/rules/rule:4' -d '{"enabled": false}'
{"data":{"rawsql":"select * from \"t/b\"","id":4,"enabled":false},"actions":[],"code":0}
1
2

删除规则:

$ curl -XDELETE --basic -u admin:public 'http://localhost:8081/api/v4/rules/rule:4'

{"code":0}
1
2
3