# 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 (opens new window). 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
支持多条件查询,其包含的查询参数有:
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
# 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 configuration
# GET /api/v4/configuration
Read all of configure parameters from broker.
Success Response Body (JSON):
Name | Type | Description |
---|---|---|
code | Integer | 0 |
data.url | String | Url of listener. |
data.num_taskq_thread | Integer | Number of taskq threads used. |
data.max_taskq_thread | Integer | Maximum number of taskq threads used。 |
data.parallel | Long | Number of parallel. |
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.tls.enable | Boolean | Enable TLS listener. |
data.tls.url | String | URL of TLS listener. |
data.tls.key | String | User's private PEM-encoded key. |
data.tls.keypass | String | String containing the user's password. Only used if the private keyfile is password-protected. |
data.tls.cert | String | User certificate data. |
data.tls.cacert | String | User's PEM-encoded CA certificates. |
data.tls.verify_peer | Boolean | Verify peer certificate. |
data.tls.fail_if_no_peer_cert | Boolean | Server will fail if the client does not have a certificate to send. |
data.websocket.enable | Boolean | Enable websocket listener. |
data.websocket.url | String | URL of websocket listener. |
data.websocket.tls_url | String | URL of TLS over websocket listerner. |
data.http_server.enable | Boolean | Enable http server listerner. |
data.http_server.port | Integer | Port of http server. |
data.http_server.username | String | User name of http server. |
data.http_server.password | String | Password of http server. |
data.bridge.bridge_mode | Boolean | Enter MQTT bridge mode . |
data.bridge.address | String | Remote Broker address. |
data.bridge.proto_ver | String | MQTT client version(3|4|5)。 |
data.bridge.clientid | String | MQTT client identifier. |
data.bridge.keepalive | Integer | Interval of keepalive. |
data.bridge.clean_start | Boolean | Clean seeson. |
data.bridge.parallel | Long | Parallel of mqtt client。 |
data.bridge.username | String | Login user name. |
data.bridge.password | String | Login password. |
data.bridge.forwards | Array[String] | Array of forward topics. |
data.bridge.forwards[0] | String | Topic. |
data.bridge.subscription | Array[Object] | Array of subscriptions. |
data.bridge.subscription[0].topic | String | Topic. |
| data.bridge.subscription[0].qos | Integer | Qos. |
Examples:
$ curl -i --basic -u admin:public -X GET 'http://127.0.0.1:8081/api/v4/configuration'
{
"code": 0,
"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
}
]
}
}
}
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
# Set Configuration
# POST /api/v4/configuration
Set configure parameters for broker.
Parameters (json):
Name | Type | Required | Value | Description |
---|---|---|---|---|
data | Object | Required | See [Get Configuration](#Get 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": {
"url": "nmq-tcp://0.0.0.0:1883",
"num_taskq_thread": 8,
"max_taskq_thread": 4,
"parallel": 32,
"property_size": 32,
"msq_len": 64,
"allow_anonymous": true,
"daemon": false,
"tls": {
"enable": false,
"url": "nmq-tls://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": "127.0.0.1:1883",
"proto_ver": 4,
"clientid": "bridge_client",
"clean_start": true,
"username": "user",
"password": "passwd",
"keepalive": 60,
"parallel": 1,
"forwards": [
"topic1/#",
"topic2/#"
],
"subscription": [
{
"topic": "cmd/topic1",
"qos": 1
}
]
}
}
}'
{"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
55
56
57
58
# 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