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)方式。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

GET /api/v4

返回 NanoMQ 支持的所有 Endpoints。

Parameters: 无

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
data	Array	Endpoints 列表
- data[0].path	String	Endpoint
- data[0].name	String	Endpoint 名
- data[0].method	String	HTTP Method
- data[0].descr	String	描述

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"}]}

Broker 基本信息

GET /api/v4/brokers

返回Broker的基本信息。

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
data	Object/Array of Objects	返回所有节点的信息*(只有一个节点，nanomq暂不支持集群)*
data.datetime	String	当前时间，格式为 "YYYY-MM-DD HH:mm:ss"
data.node_status	String	节点状态
data.sysdescr	String	软件描述
data.uptime	String	NanoMQ运行时间，格式为 "H hours, m minutes, s seconds"
data.version	String	NanoMQ 版本

$ 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"}]}

节点

GET /api/v4/nodes

返回节点的状态。

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
data	Object/Array of Objects	以 Array 形式返回所有节点的信息*(只有一个节点，nanomq暂不支持集群)*
data.connections	Integer	当前接入此节点的客户端数量
data.node_status	String	节点状态
data.uptime	String	NanoMQ 运行时间
data.version	String	NanoMQ 版本

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"}]}

客户端

GET /api/v4/clients

支持多条件查询，其包含的查询参数有：

Name	Type	Required	Description
clientid	String	False	客户端标识符
username	String	False	客户端用户名
conn_state	Enum	False	客户端当前连接状态， 可取值有：connected,idle,disconnected
clean_start	Bool	False	客户端是否使用了全新的会话
proto_name	Enum	False	客户端协议名称， 可取值有：MQTT,CoAP,LwM2M,MQTT-SN
proto_ver	Integer	False	客户端协议版本

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
data	Array of Objects	所有客户端的信息
data[0].clientid	String	客户端标识符
data[0].username	String	客户端连接时使用的用户名
data[0].proto_name	String	客户端协议名称 (MQTT,CoAP,LwM2M,MQTT-SN)
data[0].proto_ver	Integer	客户端使用的协议版本
data[0].connected	Boolean	客户端是否处于连接状态
data[0].keepalive	Integer	保持连接时间，单位：秒
data[0].clean_start	Boolean	指示客户端是否使用了全新的会话
data[0].recv_msg	Integer	接收的 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}]}

GET /api/v4/clients/{clientid}

返回指定客户端的信息

Path Parameters:

Name	Type	Required	Description
clientid	String	True	ClientID

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
data	Array 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}]}

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

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

Path Parameters:

Name	Type	Required	Description
username	String	True	Username

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
data	Array 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}]}

订阅信息

GET /api/v4/subscriptions

支持多条件查询：

Name	Type	Description
clientid	String	客户端标识符
topic	String	主题，全等查询
qos	Enum	可取值为：0,1,2
share	String	共享订阅的组名称

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
data	Array of Objects	所有订阅信息
data[0].clientid	String	客户端标识符
data[0].topic	String	订阅主题
data[0].qos	Integer	QoS 等级

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}]}

GET /api/v4/subscriptions/{clientid}

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

Path Parameters:

Name	Type	Required	Description
clientid	String	True	ClientID

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
data	Object	所有订阅信息
data.clientid	String	客户端标识符
data.topic	String	订阅主题
data.qos	Integer	QoS 等级

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}

消息发布

POST /api/v4/mqtt/publish

发布 MQTT 消息。

Parameters (json):

Name	Type	Required	Default	Description
topic	String	Optional		主题，与 topics 至少指定其中之一
topics	String	Optional		以 , 分割的多个主题，使用此字段能够同时发布消息到多个主题
clientid	String	Required		客户端标识符
payload	String	Required		消息正文
encoding	String	Optional	plain	消息正文使用的编码方式，目前仅支持 plain 与 base64 两种
qos	Integer	Optional	0	QoS 等级
retain	Boolean	Optional	false	是否为保留消息
properties	Object	Optional	{}	PUBLISH 消息里的 Property 字段

Properties取值：

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

Success Response Body (JSON):

Name	Type	Description
code	Integer	0

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}

主题订阅

POST /api/v4/mqtt/subscribe

订阅 MQTT 主题。

Parameters (json):

Name	Type	Required	Default	Description
topic	String	Optional		主题，与 topics 至少指定其中之一
topics	String	Optional		以 , 分割的多个主题，使用此字段能够同时订阅多个主题
clientid	String	Required		客户端标识符
qos	Integer	Optional	0	QoS 等级

Success Response Body (JSON):

Name	Type	Description
code	Integer	0

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}

POST /api/v4/mqtt/unsubscribe

取消订阅。

Parameters (json):

Name	Type	Required	Default	Description
topic	String	Required		主题
clientid	String	Required		客户端标识符

Success Response Body (JSON):

Name	Type	Description
code	Integer	0

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}

消息批量发布

POST /api/v4/mqtt/publish_batch

批量发布 MQTT 消息。

Parameters (json):

Name	Type	Required	Default	Description
[0].topic	String	Optional		主题，与 topics 至少指定其中之一
[0].topics	String	Optional		以 , 分割的多个主题，使用此字段能够同时发布消息到多个主题
[0].clientid	String	Required		客户端标识符
[0].payload	String	Required		消息正文
[0].encoding	String	Optional	plain	消息正文使用的编码方式，目前仅支持 plain 与 base64 两种
[0].qos	Integer	Optional	0	QoS 等级
[0].retain	Boolean	Optional	false	是否为保留消息
[0].properties	Object	Optional	{}	PUBLISH 消息里的 properties 字段

Success Response Body (JSON):

Name	Type	Description
code	Integer	0

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}

主题批量订阅

POST /api/v4/mqtt/subscribe_batch

批量订阅 MQTT 主题。

Parameters (json):

Name	Type	Required	Default	Description
[0].topic	String	Optional		主题，与 topics 至少指定其中之一
[0].topics	String	Optional		以 , 分割的多个主题，使用此字段能够同时订阅多个主题
[0].clientid	String	Required		客户端标识符
[0].qos	Integer	Optional	0	QoS 等级

Success Response Body (JSON):

Name	Type	Description
code	Integer	0

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}

POST /api/v4/mqtt/unsubscribe_batch

批量取消订阅。

Parameters (json):

Name	Type	Required	Default	Description
[0].topic	String	Required		主题
[0].clientid	String	Required		客户端标识符

Success Response Body (JSON):

Name	Type	Description
code	Integer	0

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}

主题树结构

GET /api/v4/topic-tree

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
data	Array of Objects	所有订阅信息
data[0].clientid	Array of String	客户端标识符数组
data[0].topic	String	订阅主题
data[0].cld_cnt	Integer	子节点个数

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"]}]]}

获取热更新配置

GET /api/v4/reload

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

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
data.property_size	Integer	最大属性长度。
data.msq_len	Integer	队列长度。
data.qos_duration	Integer	QOS消息定时间隔时间。
data.allow_anonymous	Boolean	允许匿名登录。
data.max_packet_size	Kbytes	NanoMQ 的最大包大小 (Kbytes)
data.client_max_packet_size	Kbytes	每个 client 的 最大包大小
data.keepalive_backoff	Integer	MQTT 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
    }
}

设置热更新配置

POST /api/v4/reload

设置热配置参数。

Parameters (json):

Name	Type	Required	Value	Description
data	Object	Required		同获取热更新配置一致 获取热更新配置。

Success Response Body (JSON):

Name	Type	Description
code	Integer	0

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}

Broker控制

POST /api/v4/ctrl/{action}

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

Path Parameters:

Name	Type	Required	Description
clientid	String	True	可取值: stop, restart

Success Response Body (JSON):

Name	Type	Description
code	Integer	0

Examples:

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

{"code":0}

规则

查询规则引擎的动作

GET /api/v4/rules/

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

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
enabled	Boolean	过滤条件：规则是否开启状态
data	Array of Objects	规则详情
data[0].id	String	规则ID
data[0].rawsql	String	SQL 语句，与请求中的 rawsql 一致

GET /api/v4/rules/{rule_id}

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

Name	Type	Required	Description
rule_id	String	False	可选，Rule ID。如不指定 rule_id 则以数组形式返回所有已创建的规则

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
enabled	Boolean	过滤条件：规则是否开启状态
data	Array of Objects	规则详情
- data.id	String	规则ID
- data.rawsql	String	SQL 语句，与请求中的 rawsql 一致

POST /api/v4/rules

创建规则，返回规则 ID。

Parameters (json):

Name	Type	Required	Description
rawsql	String	True	规则的 SQL 语句
actions	Array	True	动作列表
- actions[0].name	String	True	动作名称 (include repub, mysql, sqlite)
- actions[0].params	Object	True	动作参数。参数以 key-value 形式表示。详情可参看添加规则的示例
description	String	False	可选，规则描述

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
enabled	Boolean	过滤条件：规则是否开启状态
data	Array of Objects	规则详情
- data.id	String	规则ID
- data.rawsql	String	SQL 语句，与请求中的 rawsql 一致

PUT /api/v4/rules/{rule_id}

更新规则，返回规则 ID。

Parameters (json):

Name	Type	Required	Description
rawsql	String	True	可选，规则的 SQL 语句
actions	Array	True	可选，动作列表
- actions[0].name	String	True	可选，动作名称
- actions[0].params	Object	True	可选，动作参数。参数以 key-value 形式表示。详情可参看添加规则的示例
description	String	False	可选，规则描述

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
enabled	Boolean	过滤条件：规则是否开启状态
data	Array of Objects	规则详情
- data.id	String	规则ID
- data.rawsql	String	SQL 语句，与请求中的 rawsql 一致

DELETE /api/v4/rules/{rule_id}

删除规则。

Parameters: 无

Success Response Body (JSON):

Name	Type	Description
code	Integer	0

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}

使用规则 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}

获取所有的规则，注意返回值里的 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}

更新一下规则的 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}

停用规则 (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}

删除规则:

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

{"code":0}