# HTTP API (V4)
NanoMQ Broker provides HTTP APIs for integration with external systems, such as querying broker statistics information, clients information, subscribe topics information, and restart with new config file.
NanoMQ Broker's HTTP API service listens on port 8081 by default. You can modify the listening port through the configuration file of etc/nanomq.conf
. All API calls with api/v4
.
The previous version: HTTP-API (v1)
# Interface security
NanoMQ Broker's HTTP API uses the method of Basic Authentication (opens new window) or JWT Authentication. The username
and password
must be filled. The default username
and password
are: admin/public
. You can modify username and password through the configuration file of etc/nanomq.conf
.
# Response code
# HTTP status codes
The NanoMQ Broker interface always returns 200 OK when the call is successful, and the response content is returned in JSON format.
The possible status codes are as follows:
Status Code | Description |
---|---|
200 | Succeed, and the returned JSON data will provide more information |
400 | Invalid client request, such as wrong request body or parameters |
401 | Client authentication failed , maybe because of invalid authentication credentials |
404 | The requested path cannot be found or the requested object does not exist |
500 | An internal error occurred while the server was processing the request |
# result codes
The response message body of the NanoMQ Broker interface is in JSON format, which always contains the returned code
.
The possible returned codes are as follows:
Return Code | Description |
---|---|
0 | Succeed |
101 | RPC error |
102 | unknown mistake |
103 | wrong user name or password |
104 | Empty username or password |
105 | User does not exist |
106 | Administrator account cannot be deleted |
107 | Missing key request parameters |
108 | Request parameter error |
109 | Request parameters are not in legal JSON format |
110 | Plug-in is enabled |
111 | Plugin is closed |
112 | Client is offline |
113 | User already exists |
114 | Old password is wrong |
115 | Illegal subject |
116 | Token expired |
# API Endpoints
# GET /api/v4
Return all Endpoints supported by NanoMQ Broker.
Parameters: 无
Success Response Body (JSON):
Name | Type | Description |
---|---|---|
code | Integer | 0 |
data | Array | Endpoints list |
- data[0].path | String | Endpoint |
- data[0].name | String | Endpoint Name |
- data[0].method | String | HTTP Method |
- data[0].descr | String | Description |
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"}]}
2
3
# Broker Basic Information
# GET /api/v4/brokers
Return basic information of NanoMQ Broker.
Success Response Body (JSON):
Name | Type | Description |
---|---|---|
code | Integer | 0 |
data | Object/Array of Objects | Returns the information of all nodes*(Only one node for NanoMQ)* |
data.datetime | String | Current time, in the format of "YYYY-MM-DD HH: mm: ss" |
data.node_status | String | Node status |
data.sysdescr | String | Software description |
data.uptime | String | NanoMQ Broker runtime, in the format of "H hours, m minutes, s seconds" |
data.version | String | NanoMQ Broker version |
$ 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"}]}
2
3
# Node
# GET /api/v4/nodes
Return the status of the node.
Success Response Body (JSON):
Name | Type | Description |
---|---|---|
code | Integer | 0 |
data | Object/Array of Objects | Returns information about all nodes in an Array |
data.connections | Integer | Number of clients currently connected to this node |
data.node_status | String | Node status |
data.uptime | String | NanoMQ Broker runtime |
data.version | String | NanoMQ Broker version |
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"}]}
2
3
# Client
# GET /api/v4/clients
Multiple conditions are supported. The query parameters included are shown below.
Name | Type | Required | Description |
---|---|---|---|
clientid | String | False | Client identifier |
username | String | False | Client username |
conn_state | Enum | False | The current connection status of the client, the possible values areconnected ,idle ,disconnected |
clean_start | Bool | False | Whether the client uses a new session |
proto_name | Enum | False | Client protocol name, the possible values areMQTT ,CoAP ,LwM2M ,MQTT-SN |
proto_ver | Integer | False | Client protocol version |
Success Response Body (JSON):
Name | Type | Description |
---|---|---|
code | Integer | 0 |
data | Array of Objects | Information for all clients |
data[0].clientid | String | Client identifier |
data[0].username | String | User name of client when connecting |
data[0].proto_name | String | Client protocol name*(MQTT,CoAP,LwM2M,MQTT-SN)* |
data[0].proto_ver | Integer | Protocol version used by the client |
data[0].connected | Boolean | Whether the client is connected |
data[0].keepalive | Integer | keepalive time, with the unit of second |
data[0].clean_start | Boolean | Indicate whether the client is using a brand new session |
data[0].recv_msg | Integer | Number of PUBLISH packets received |
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}]}
2
3
# GET /api/v4/clients/{clientid}
Returns information for the specified client
Path Parameters:
Name | Type | Required | Description |
---|---|---|---|
clientid | String | True | ClientID |
Success Response Body (JSON):
Name | Type | Description |
---|---|---|
code | Integer | 0 |
data | Array of Objects | Client information, for details, see [GET /api/v4/clients](#GET /api/v4/clients) |
Examples:
Query the specified client
$ 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}]}
2
3
# GET /api/v4/clients/username/{username}
Query client information by Username. Since there may be multiple clients using the same user name, multiple client information may be returned at the same time.
Path Parameters:
Name | Type | Required | Description |
---|---|---|---|
username | String | True | Username |
Success Response Body (JSON):
Name | Type | Description |
---|---|---|
code | Integer | 0 |
data | Array of Objects | Information about clients, for details, see [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}]}
2
3
# Subscription Information
# GET /api/v4/subscriptions
Multiple conditions queries are supported:
Name | Type | Description |
---|---|---|
clientid | String | Client identifier |
topic | String | congruent query |
qos | Enum | Possible values are 0, 1, 2` |
share | String | Shared subscription group name |
Success Response Body (JSON):
Name | Type | Description |
---|---|---|
code | Integer | 0 |
data | Array of Objects | All subscription information |
data[0].clientid | String | Client identifier |
data[0].topic | String | Subscribe to topic |
data[0].qos | Integer | QoS level |
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}]}
2
3
# GET /api/v4/subscriptions/{clientid}
Return the subscription information of the specified client in the Broker.
Path Parameters:
Name | Type | Required | Description |
---|---|---|---|
clientid | String | True | ClientID |
Success Response Body (JSON):
Name | Type | Description |
---|---|---|
code | Integer | 0 |
data | Object | All subscription information |
data.clientid | String | Client identifier |
data.topic | String | Subscribe to topic |
data.qos | Integer | QoS level |
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}
2
3
# Publish message
# POST /api/v4/mqtt/publish
Publish MQTT message。
Parameters (json):
Name | Type | Required | Default | Description |
---|---|---|---|---|
topic | String | Optional | For topic and topics, with at least one of them specified | |
topics | String | Optional | Multiple topics separated by , . This field is used to publish messages to multiple topics at the same time | |
clientid | String | Required | Client identifier | |
payload | String | Required | Message body | |
encoding | String | Optional | plain | The encoding used in the message body. Currently only plain and base64 are supported. |
qos | Integer | Optional | 0 | QoS level |
retain | Boolean | Optional | false | Whether it is a retained message |
properties | Object | Optional | {} | The Properties of the PUBLISH message |
Properties:
Name | Type | Description| |
---|---|---|
payload_format_indicator | Integer | 0 (0x00) Byte Indicates that the Payload is unspecified bytes, which is equivalent to not sending a Payload Format Indicator. 1 (0x01) Byte Indicates that the Payload is UTF-8 Encoded Character Data. The UTF-8 data in the Payload MUST be well-formed UTF-8 as defined by the Unicode specification and restated in RFC 3629 |
message_expiry_interval | integer | Identifier of the Message Expiry Interval. If the Message Expiry Interval has passed and the Server has not managed to start onward delivery to a matching subscriber, then it MUST delete the copy of the message for that subscriber |
response_topic | String | Identifier of the Response Topic.The Response Topic MUST be a UTF-8 Encoded, It MUST NOT contain wildcard characters. |
correlation_data | String | Identifier of the Correlation Data. The Server MUST send the Correlation Data unaltered to all subscribers receiving the Application Message |
subscription_identifier | Integer | Identifier of the Subscription Identifier. It can have the value of 1 to 268,435,455. It is a Protocol Error if the Subscription Identifier has a value of 0. Multiple Subscription Identifiers will be included if the publication is the result of a match to more than one subscription, in this case their order is not significant. |
content_type | String | The Content Type MUST be a UTF-8 Encoded String |
user_properties | Object | Identifier of the User Property. The Server send all User Properties unaltered in a PUBLISH packet when forwarding the Application Message to a Client |
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": "emqx", "foo": "bar"}, "content_type": "text/plain"}}'
{"code":0}
2
3
4
# Subscribe to topic
# POST /api/v4/mqtt/subscribe
Subscribe to MQTT topic
Parameters (json):
Name | Type | Required | Default | Description |
---|---|---|---|---|
topic | String | Optional | For topic and topics, with at least one of them specified | |
topics | String | Optional | Multiple topics separated by , . This field is used to subscribe to multiple topics at the same time | |
clientid | String | Required | Client identifier | |
qos | Integer | Optional | 0 | QoS level |
Success Response Body (JSON):
Name | Type | Description |
---|---|---|
code | Integer | 0 |
Examples:
Subscribe to the three topics of a
, b
, c
at the same time
$ 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}
2
3
# POST /api/v4/mqtt/unsubscribe
Unsubscribe.
Parameters (json):
Name | Type | Required | Default | Description |
---|---|---|---|---|
topic | String | Required | Topic | |
clientid | String | Required | Client identifier |
Success Response Body (JSON):
Name | Type | Description |
---|---|---|
code | Integer | 0 |
Examples:
Unsubscribe from a topic
$ curl -i --basic -u admin:public -X POST "http://localhost:8081/api/v4/mqtt/unsubscribe" -d '{"topic":"a","qos":1,"clientid":"example"}'
{"code":0}
2
3
# Message publish in batch
# POST /api/v4/mqtt/publish_batch
Publish MQTT messages in batch.
Parameters (json):
Name | Type | Required | Default | Description |
---|---|---|---|---|
[0].topic | String | Optional | Topic, at least one of which is specified with topics | |
[0].topics | String | Optional | Multiple topics divided by , , which can be used to publish messages to multiple topics at the same time | |
[0].clientid | String | Required | Client identifier | |
[0].payload | String | Required | Message body | |
[0].encoding | String | Optional | plain | The encoding method used in the message body, only plain and base64 are supported currently |
[0].qos | Integer | Optional | 0 | QoS level |
[0].retain | Boolean | Optional | false | Whether it is a retained message or not |
[0].properties | Object | Optional | {} | The Properties of the PUBLISH message |
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}
2
3
# Topic subscription in batch
# POST /api/v4/mqtt/subscribe_batch
Subscribe to MQTT topics in batch.
Parameters (json):
Name | Type | Required | Default | Description |
---|---|---|---|---|
[0].topic | String | Optional | Topic, at least one of which is specified with topics | |
[0].topics | String | Optional | Multiple topics divided by , , which can be used to publish messages to multiple topics at the same time | |
[0].clientid | String | Required | Client identifier | |
[0].qos | Integer | Optional | 0 | QoS level |
Success Response Body (JSON):
Name | Type | Description |
---|---|---|
code | Integer | 0 |
Examples:
Subscribe to the three topics of a
,b
, and c
at one time
$ 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}
2
3
# POST /api/v4/mqtt/unsubscribe_batch
Unsubscribe in batch.
Parameters (json):
Name | Type | Required | Default | Description |
---|---|---|---|---|
[0].topic | String | Required | Topic | |
[0].clientid | String | Required | Client identifier |
Success Response Body (JSON):
Name | Type | Description |
---|---|---|
code | Integer | 0 |
Examples:
Unsubscribe from a
,b
topics at one time
$ 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}
2
3
# Topic tree structure
# 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 | Array of client identifies |
data[0].topic | String | Subscribe to topic |
data[0].cld_cnt | Integer | Number of child node |
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"]}]]}
2
3
# Get hot updatable configuration
# GET /api/v4/reload
Return all configuration that can be hot updatable.
Success Response Body (JSON):
Name | Type | Description |
---|---|---|
code | Integer | 0 |
data.property_size | Integer | Max size for a MQTT property. |
data.msq_len | Integer | Queue length for resending messages. |
data.qos_duration | Integer | The interval of the qos timer. |
data.allow_anonymous | Boolean | Allow anonymous login. |
data.max_packet_size | Kbytes | The max packet size of NanoMQ (Kbytes). |
data.client_max_packet_size | Kbytes | The default max packet size of each client. |
data.keepalive_backoff | Integer | The backoff for MQTT keepalive timeout. |
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
}
}
2
3
4
5
6
7
8
9
10
11
12
13
14
# Hot update configuration
# POST /api/v4/reload
Set configuration that can be hot updatable.
Parameters (json):
Name | Type | Required | Value | Description |
---|---|---|---|---|
data | Object | Required | See [Get hot updatable configuration](#Get hot updatable configuration)。 |
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}
2
3
4
5
6
7
8
9
10
11
12
13
14
# Get bridges configuration
# GET /api/v4/bridges/
Get all nodes configuration of bridges
Success Response Body (JSON):
Name | Type | Description |
---|---|---|
code | Integer | 0 |
data | Array of Objects | All configuration of bridges' node |
data.bridges.nodes[0].name | String | Node name |
data.bridges.nodes[0].enable | Boolean | Enter MQTT bridge mode (default false ). |
data.bridges.nodes[0].connector.server | String | Remote Broker address. |
data.bridges.nodes[0].connector.proto_ver | Boolean | MQTT client version(4|5). |
data.bridges.nodes[0].connector.clientid | String | MQTT client identifier. |
data.bridges.nodes[0].connector.keepalive | Integer | Interval of keepalive. |
data.bridges.nodes[0].connector.clean_start | Boolean | Clean session. |
data.bridges.nodes[0].connector.username | String | Login user name. |
data.bridges.nodes[0].connector.password | String | Login password. |
data.bridges.nodes[0].connector.conn_properties | Object | MQTT V5 Property of Connector (see table below) |
data.bridges.nodes[0].connector.ssl.enable | Boolean | Launch TLS ( default false)。 |
data.bridges.nodes[0].connector.ssl.key_password | String | String containing the user's password. only used if the private keyfile is password-protected. |
data.bridges.nodes[0].connector.ssl.keyfile | String | User's private PEM-encoded key. |
data.bridges.nodes[0].connector.ssl.certfile | String | User certificate data. |
data.bridges.nodes[0].connector.ssl.cacertfile | String | User's PEM-encoded CA certificates. |
data.bridges.nodes[0].quic_keepalive | Duration | Interval of a sending keepalive packet via QUIC transport., (default 120s ) |
data.bridges.nodes[0].quic_idle_timeout | Duration | How long a connection can go idle before it is gracefully shut down. 0 to disable timeout, which may lost disconnect event msg. (default 120s ) |
data.bridges.nodes[0].quic_discon_timeout | Duration | How long to wait for an ACK before declaring a path dead and disconnecting, This affects stream living time.(default 20s ) |
data.bridges.nodes[0].quic_handshake_timeout | Duration | The Max time NanoMQ waits for establishing QUIC connection(default 60s ) |
data.bridges.nodes[0].hybrid_bridging | Boolean | Hybrid bridging: enable or disable the hybrid bridging mode,(default: false ), recommend to enable it when you want to take advantage of QUIC |
data.bridges.nodes[0].quic_send_idle_timeout | Duration | Reset congestion control after being idle SendIdleTimeout (default 60s ) |
data.bridges.nodes[0].quic_initial_rtt_ms | Duration | Initial RTT estimate. (ms) (default: 800ms ) |
data.bridges.nodes[0].quic_max_ack_delay_ms | Duration | How long to wait after receiving data before sending an ACK. (default: 100ms ) |
data.bridges.nodes[0].quic_qos_priority | Boolean | Send QoS 1/2 msg in high prority. (default: true ) |
data.bridges.nodes[0].quic_0rtt | Boolean | 0RTT is a feature of QUIC to re-establish connection quickly. . (default: true ) |
data.bridges.nodes[0].multi_stream | Boolean | Multiple stream option,(default false ) |
data.bridges.nodes[0].parallel | Long | Parallel of mqtt client. |
data.bridges.nodes[0].forwards | Array[String] | Array of forward topics. |
data.bridges.nodes[0].subscription[0].topic | String | First Topic . |
data.bridges.nodes[0].subscription[0].qos | Integer | First Qos . |
data.bridges.nodes[0].sub_properties | Object | MQTT V5 Property of Subscription (see table below) |
data.bridges.nodes[0].max_send_queue_len | Integer | Maximum number of message send queue length |
data.bridges.nodes[0].max_recv_queue_len | Integer | Maximum number of message receive queue length |
Examples:
$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/bridges"
{
"code": 0,
"data": {
"bridge": {
"nodes": [
{
"name": "emqx",
"enable": true,
"parallel": 2,
"connector": {
"server": "mqtt-tcp://broker.emqx.io:1883",
"proto_ver": 5,
"clientid": null,
"clean_start": true,
"username": "",
"password": "",
"keepalive": 60,
"conn_properties": {
"session_expiry_interval": 30,
"receive_maximum": 65535,
"maximum_packet_size": 0,
"topic_alias_maximum": 0,
"request_response_information": false,
"request_problem_information": true
},
"will_properties": {
"payload_format_indicator": 0,
"message_expiry_interval": 360,
"will_delay_interval": 20,
"user_properties": [
{
"key": "key1",
"value": "value1"
},
{
"key": "key2",
"value": "value2"
}
]
}
},
"forwards": [
"topic1/#",
"topic2/#"
],
"subscription": [
{
"topic": "cmd/topic1",
"qos": 1
},
{
"topic": "cmd/topic2",
"qos": 2
}
],
"sub_properties": {
"identifier": 1,
"user_properties": [
{
"key": "key1",
"value": "value1"
},
{
"key": "key2",
"value": "value2"
}
]
},
"tls": {
"enable": false,
"url": null,
"key_password": null,
"key": null,
"cert": null,
"cacert": null,
"verify_peer": false,
"fail_if_no_peer_cert": false
}
}
]
}
}
}
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
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
# GET /api/v4/bridges/{bridge_name}
Returns configuration for the specified bridge node.
Path Parameters:
Name | Type | Required | Description |
---|---|---|---|
bridge_name | String | True | bridge node name |
Success Response Body (JSON):
Name | Type | Description |
---|---|---|
code | Integer | 0 |
data | Array of Objects | for details, see [GET /api/v4/bridges](#GET /api/v4/bridges/) |
Example:
$ curl -i --basic -u admin:public -X GET "http://localhost:8081/api/v4/bridges/emqx"
{
"code": 0,
"data": {
"bridge": {
"nodes": [
{
"name": "emqx",
"enable": true,
"parallel": 2,
"connector": {
"server": "mqtt-tcp://broker.emqx.io:1883",
"proto_ver": 5,
"clientid": null,
"clean_start": true,
"username": "",
"password": "",
"keepalive": 60,
"conn_properties": {
"session_expiry_interval": 30,
"receive_maximum": 65535,
"maximum_packet_size": 0,
"topic_alias_maximum": 0,
"request_response_information": false,
"request_problem_information": true
},
"will_properties": {
"payload_format_indicator": 0,
"message_expiry_interval": 360,
"will_delay_interval": 20,
"user_properties": [
{
"key": "key1",
"value": "value1"
},
{
"key": "key2",
"value": "value2"
}
]
}
},
"forwards": [
"topic1/#",
"topic2/#"
],
"subscription": [
{
"topic": "cmd/topic1",
"qos": 1
},
{
"topic": "cmd/topic2",
"qos": 2
}
],
"sub_properties": {
"identifier": 1,
"user_properties": [
{
"key": "key1",
"value": "value1"
},
{
"key": "key2",
"value": "value2"
}
]
},
"tls": {
"enable": false,
"url": null,
"key_password": null,
"key": null,
"cert": null,
"cacert": null,
"verify_peer": false,
"fail_if_no_peer_cert": false
}
}
]
}
}
}
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
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
# Update bridge configuration
# PUT /api/v4/bridges/{bridge_name}
update bridge configuration
Path Parameters:
Name | Type | Required | Description |
---|---|---|---|
bridge_name | String | True | bridge node name |
Success Response Body (JSON):
Name | Type | Description |
---|---|---|
code | Integer | 0 |
data | Objects | 桥接客户端配置信息 |
data.name | String | Node name |
data.enable | Boolean | Enter MQTT bridge mode (default false ). |
data.connector.server | String | Remote Broker address. |
data.connector.proto_ver | Boolean | MQTT client version(4|5). |
data.connector.clientid | String | MQTT client identifier. |
data.connector.keepalive | Integer | Interval of keepalive. |
data.connector.clean_start | Boolean | Clean session. |
data.connector.username | String | Login user name. |
data.connector.password | String | Login password. |
data.connector.conn_properties | Object | MQTT V5 Property of Connector (see table below) |
data.connector.ssl.enable | Boolean | Launch TLS ( default false)。 |
data.connector.ssl.key_password | String | String containing the user's password. only used if the private keyfile is password-protected. |
data.connector.ssl.keyfile | String | User's private PEM-encoded key. |
data.connector.ssl.certfile | String | User certificate data. |
data.connector.ssl.cacertfile | String | User's PEM-encoded CA certificates. |
data.quic_keepalive | Duration | Interval of a sending keepalive packet via QUIC transport., (default 120s ) |
data.quic_idle_timeout | Duration | How long a connection can go idle before it is gracefully shut down. 0 to disable timeout, which may lost disconnect event msg. (default 120s ) |
data.quic_discon_timeout | Duration | How long to wait for an ACK before declaring a path dead and disconnecting, This affects stream living time.(default 20s ) |
data.quic_handshake_timeout | Duration | The Max time NanoMQ waits for establishing QUIC connection(default 60s ) |
data.hybrid_bridging | Boolean | Hybrid bridging: enable or disable the hybrid bridging mode,(default: false ), recommend to enable it when you want to take advantage of QUIC |
data.quic_send_idle_timeout | Duration | Reset congestion control after being idle SendIdleTimeout (default 60s ) |
data.quic_initial_rtt_ms | Duration | Initial RTT estimate. (ms) (default: 800ms ) |
data.quic_max_ack_delay_ms | Duration | How long to wait after receiving data before sending an ACK. (default: 100ms ) |
data.quic_qos_priority | Boolean | Send QoS 1/2 msg in high prority. (default: true ) |
data.quic_0rtt | Boolean | 0RTT is a feature of QUIC to re-establish connection quickly. . (default: true ) |
data.multi_stream | Boolean | Multiple stream option,(default false ) |
data.parallel | Long | Parallel of mqtt client. |
data.forwards | Array[String] | Array of forward topics. |
data.subscription[0].topic | String | First Topic . |
data.subscription[0].qos | Integer | First Qos . |
data.sub_properties | Object | MQTT V5 Property of Subscription (see table below) |
data.max_send_queue_len | Integer | Maximum number of message send queue length |
data.max_recv_queue_len | Integer | Maximum number of message receive queue length |
Example:
$ curl -i --basic -u admin:public -X PUT 'http://localhost:8081/api/v4/bridges/emqx' \
-d '{
"data": {
"name": "emqx",
"enable": true,
"parallel": 8,
"connector": {
"server": "mqtt-tcp://broker.emqx.io:1883",
"proto_ver": 4,
"clientid": null,
"clean_start": false,
"username": "emqx",
"password": "emqx123",
"keepalive": 60
},
"forwards": [
"topic1/#",
"topic2/#"
],
"subscription": [
{
"topic": "cmd/topic1",
"qos": 1
},
{
"topic": "cmd/topic2",
"qos": 2
}
],
"tls": {
"enable": false,
"url": null,
"key_password": null,
"key": null,
"cert": null,
"cacert": null,
"verify_peer": false,
"fail_if_no_peer_cert": false
},
"quic_keepalive": "100s",
"quic_idle_timeout": "100s",
"quic_discon_timeout": "100s",
"quic_send_idle_timeout": "20s",
"quic_initial_rtt_ms": "800s",
"quic_max_ack_delay_ms": "100s",
"quic_multi_stream": true,
"hybrid_bridging": true,
"quic_qos_priority": true,
"quic_0rtt": true
}
}'
{"code":0}
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
# Broker Control
# POST /api/v4/ctrl/{action}
Stop or Restart the NanoMQ Broker(Usually used after the configuration is modified).
Path Parameters:
Name | Type | Required | Description |
---|---|---|---|
clientid | String | True | Possible values are 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}
2
3
# Rule
Query rule engine actions
# GET /api/v4/rules/
Get rule list, including the rule's SQL, id, etc.
Success Response Body (JSON):
Name | Type | Description |
---|---|---|
code | Integer | 0 |
enabled | Boolean | Filter condition: whether the rule is enabled or not |
data | Array of Objects | rule detail |
data[0].id | String | Rule ID |
data[0].rawsql | String | SQL statement, consistent with rawsql in the request |
# GET /api/v4/rules/{rule_id}
Get the details of a rule, including the rule's SQL, id , etc.Path Parameters:
Name | Type | Required | Description |
---|---|---|---|
rule_id | String | False | Optional, Rule ID. If rule_id is not specified then returns all created rules in an array |
Success Response Body (JSON):
Name | Type | Description |
---|---|---|
code | Integer | 0 |
enabled | Boolean | Filter condition: whether the rule is enabled or not |
data | Object | Rule object |
- data.id | String | Rule ID |
- data.rawsql | String | SQL statement, consistent with rawsql in the request |
# POST /api/v4/rules
Create a rule and return the rule ID.
Parameters (json):
Name | Type | Required | Description |
---|---|---|---|
rawsql | String | True | SQL statements of rules |
actions | Array | True | Action list |
- actions[0].name | String | True | Action name (include repub, mysql, sqlite) |
- actions[0].params | Object | True | Action parameters, that is expressed in key-value form. For details, please refer to the example of adding rules |
description | String | False | Optional, rule description |
Success Response Body (JSON):
Name | Type | Description |
---|---|---|
code | Integer | 0 |
enabled | Boolean | Filter condition: whether the rule is enabled or not |
data | Object | Rule object |
- data.id | String | Rule ID |
- data.rawsql | String | SQL statement, consistent with rawsql in the request |
# PUT /api/v4/rules/{rule_id}
Update the rule and return the rule ID.
Parameters (json):
Name | Type | Required | Description |
---|---|---|---|
rawsql | String | True | Optional, SQL statement of the rule |
actions | Array | True | Optional, action list |
- actions[0].name | String | True | Optional, action name |
- actions[0].params | Object | True | Optional, action parameters, that is expressed in key-value form. For details, please refer to the example of adding rules |
description | String | False | Optional, rule description |
Success Response Body (JSON):
Name | Type | Description |
---|---|---|
code | Integer | 0 |
enabled | Boolean | Filter condition: whether the rule is enabled or not |
data | Object | Rule object |
- data.id | String | Rule ID |
- data.rawsql | String | SQL statement, consistent with rawsql in the request |
# DELETE /api/v4/rules/{rule_id}
Delete the rule
Parameters: None
Success Response Body (JSON):
Name | Type | Description |
---|---|---|
code | Integer | 0 |
Examples:
Add a rule to print the rule running parameters for all messages matching the topic "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}
2
3
4
5
6
7
8
9
10
11
12
13
Use the rule ID to get the details of the rule just created:
$ 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}
2
3
Get all the rules. Note that the data in the returned value is an array of rule objects:
$ 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}
2
3
Update the SQL statement of the rule to 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}
2
3
Disable the rule:
$ 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}
2
Delete the rule:
$ curl -XDELETE --basic -u admin:public 'http://localhost:8081/api/v4/rules/rule:4'
{"code":0}
2
3
- Interface security
- Response code
- API Endpoints
- Broker Basic Information
- Node
- Client
- Subscription Information
- Publish message
- Subscribe to topic
- Message publish in batch
- Topic subscription in batch
- Topic tree structure
- Get hot updatable configuration
- Hot update configuration
- Get bridges configuration
- Update bridge configuration
- Broker Control
- Rule