REST API

The REST API allows you to query MQTT clients, sessions, subscriptions, and routes. You can also query and monitor the metrics and statistics of the broker.

Base URL

All REST APIs in the documentation have the following base URL:

http(s)://host:8080/api/v2/

Basic Authentication

The HTTP requests to the REST API are protected with HTTP Basic authentication, For example:

curl -v --basic -u <user>:<passwd> -k http://localhost:8080/api/v2/nodes/emq@127.0.0.1/clients

Nodes

List all Nodes in the Cluster

Definition:

GET api/v2/management/nodes

Response:

{
    "code": 0,
    "result":
    [
        {
            "name": "emq@127.0.0.1",
            "version": "2.1.1",
            "sysdescr": "EMQ",
            "uptime": "1 hours, 17 minutes, 1 seconds",
            "datetime": "2017-04-14 14:11:38",
            "otp_release": "R19/8.3",
            "node_status": "Running"
        }
    ]
}

Retrieve a Node’s Info

Definition:

GET api/v2/management/nodes/{node_name}

Example Request:

GET api/v2/management/nodes/emq@127.0.0.1

Response:

{
    "code": 0,
    "result":
    {
        "version": "2.1.1",
        "sysdescr": "EMQ X",
        "uptime": "1 hours, 17 minutes, 18 seconds",
        "datetime": "2017-04-14 14:11:55",
        "otp_release": "R19/8.3",
        "node_status": "Running"
    }
}

List all Nodes’statistics in the Cluster

Definition:

GET api/v2/monitoring/nodes

Response:

{
    "code": 0,
    "result":
    [
        {
            "name": "emq@127.0.0.1",
            "otp_release": "R19/8.3",
            "memory_total": "69.19M",
            "memory_used": "49.28M",
            "process_available": 262144,
            "process_used": 303,
            "max_fds": 256,
            "clients": 1,
            "node_status": "Running",
            "load1": "1.93",
            "load5": "1.93",
            "load15": "1.89"
        }
    ]
}

Retrieve a node’s statistics

Definition:

GET api/v2/monitoring/nodes/{node_name}

Example Request:

GET api/v2/monitoring/nodes/emq@127.0.0.1

Response:

{
    "code": 0,
    "result":
    {
        "name": "emq@127.0.0.1",
        "otp_release": "R19/8.3",
        "memory_total": "69.19M",
        "memory_used": "49.24M",
        "process_available": 262144,
        "process_used": 303,
        "max_fds": 256,
        "clients": 1,
        "node_status": "Running",
        "load1": "2.21",
        "load5": "2.00",
        "load15": "1.92"
    }
}

Clients

List all Clients on a Node

Definition:

GET api/v2/nodes/{node_name}/clients

Request parameter:

curr_page={page_no}&page_size={page_size}

Example Request:

GET api/v2/nodes/emq@127.0.0.1/clients

Response:

{
    "code": 0,
    "result":
    {
        "current_page": 1,
        "page_size": 20,
        "total_num": 1,
        "total_page": 1,
        "objects":
        [
            {
                "client_id": "C_1492145414740",
                "username": "undefined",
                "ipaddress": "127.0.0.1",
                "port": 49639,
                "clean_sess": true,
                "proto_ver": 4,
                "keepalive": 60,
                "connected_at": "2017-04-14 12:50:15"
            }
        ]
    }
}

Retrieve a Client on a Node

Definition:

GET api/v2/nodes/{node_name}/clients/{client_id}

Example Request:

GET api/v2/nodes/emq@127.0.0.1/clients/C_1492145414740

Response:

{
    "code": 0,
    "result":
    {
        "objects":
        [
            {
                "client_id": "C_1492145414740",
                "username": "undefined",
                "ipaddress": "127.0.0.1",
                "port": 50953,
                "clean_sess": true,
                "proto_ver": 4,
                "keepalive": 60,
                "connected_at": "2017-04-14 13:35:15"
            }
        ]
    }
}

Retrieve a Client in the Cluster

Definition:

GET api/v2/clients/{client_id}

Example Request:

GET api/v2/clients/C_1492145414740

Response:

{
    "code": 0,
    "result":
    {
        "objects":
        [
            {
                "client_id": "C_1492145414740",
                "username": "undefined",
                "ipaddress": "127.0.0.1",
                "port": 50953,
                "clean_sess": true,
                "proto_ver": 4,
                "keepalive": 60,
                "connected_at": "2017-04-14 13:35:15"
            }
        ]
    }
}

Sessions

List all Sessions on a Node

Definition:

GET api/v2/node/{node_name}/sessions?curr_page=1&page_size=20

Example Request:

GET api/v2/nodes/emq@127.0.0.1/sessions

Response:

{
    "code": 0,
    "result":
    {
        "current_page": 1,
        "page_size": 20,
        "total_num": 1,
        "total_page": 1,
        "objects":
        [
            {
                "client_id": "C_1492145414740",
                "clean_sess": true,
                "max_inflight": "undefined",
                "inflight_queue": "undefined",
                "message_queue": "undefined",
                "message_dropped": "undefined",
                "awaiting_rel": "undefined",
                "awaiting_ack": "undefined",
                "awaiting_comp": "undefined",
                "created_at": "2017-04-14 13:35:15"
            }
        ]
    }
}

Retrieve a Session on a Node

Definition:

GET api/v2/nodes/{node_name}/sessions/{client_id}

Example Request:

GET api/v2/nodes/emq@127.0.0.1/sessions/C_1492145414740

Response:

{
    "code": 0,
    "result":
    {
        "objects":
        [
            {
                "client_id": "C_1492145414740",
                "clean_sess": true,
                "max_inflight": "undefined",
                "inflight_queue": "undefined",
                "message_queue": "undefined",
                "message_dropped": "undefined",
                "awaiting_rel": "undefined",
                "awaiting_ack": "undefined",
                "awaiting_comp": "undefined",
                "created_at": "2017-04-14 13:35:15"
            }
        ]
    }
}

Retrieve a Session in the Cluster

Definition:

GET api/v2/sessions/{client_id}

Example Request:

GET api/v2/sessions/C_1492145414740

Response:

{
    "code": 0,
    "result":
    {
        "objects":
        [
            {
                "client_id": "C_1492145414740",
                "clean_sess": true,
                "max_inflight": "undefined",
                "inflight_queue": "undefined",
                "message_queue": "undefined",
                "message_dropped": "undefined",
                "awaiting_rel": "undefined",
                "awaiting_ack": "undefined",
                "awaiting_comp": "undefined",
                "created_at": "2017-04-14 13:35:15"
            }
        ]
    }
}

Subscriptions

List all Subscriptions of a Node

Definition:

GET api/v2/nodes/{node_name}/subscriptions

Request parameters:

curr_page={page_no}&page_size={page_size}

Example Request:

GET api/v2/nodes/emq@127.0.0.1/subscriptions

Response:

{
    "code": 0,
    "result":
    {
        "current_page": 1,
        "page_size": 20,
        "total_num": 1,
        "total_page": 1,
        "objects":
        [
            {
                "client_id": "C_1492145414740",
                "topic": "$client/C_1492145414740",
                "qos": 1
            }
        ]
    }
}

List Subscriptions of a Client

Definition:

GET api/v2/subscriptions/{cliet_id}

Example Request:

GET api/v2/subscriptions/C_1492145414740

Response:

{
    "code": 0,
    "result":
    {
        "objects":
        [
            {
                "client_id": "C_1492145414740",
                "topic": "$client/C_1492145414740",
                "qos": 1
            }
        ]
    }
}

Create a Subscription

Definition:

POST api/v2/mqtt/subscribe

Reqeust parameters:

{
    "topic": "test",
    "qos": 1,
    "client_id": "C_1492145414740"
}

Response:

{
    "code": 0,
    "result": []
}

Routes

List all Routes in the Cluster

Definition:

GET api/v2/routes

Request parameters:

curr_page={page_no}&page_size={page_size}

Response:

{
    "code": 0,
    "result":
    {
        "current_page": 1,
        "page_size": 20,
        "total_num": 1,
        "total_page": 1,
        "objects":
        [
            {
                "topic": "$client/C_1492145414740",
                "node": "emq@127.0.0.1"
            }
        ]
    }
}

Retrieve a Route in the Cluster

Definition:

GET api/v2/routes/{topic}

Example Request:

GET api/v2/routes/topic

Response:

{
    "code": 0,
    "result":
    {
        "objects":
        [
            {
                "topic": "topic",
                "node": "emq@127.0.0.1"
            }
        ]
    }
}

Plugins

List all Plugins of a Node

Definition:

GET /api/v2/nodes/{node_name}/plugins/

Response:

{
    "code": 0,
    "result": [
        {
            "name": "emq_auth_clientid",
            "version": "2.3",
            "description": "Authentication with ClientId/Password",
            "active": false
        },
        {
            "name": "emq_auth_http",
            "version": "2.3",
            "description": "Authentication/ACL with HTTP API",
            "active": false
        },
        {
            "name": "emq_auth_jwt",
            "version": "2.3",
            "description": "Authentication with jwt",
            "active": false
        },
        {
            "name": "emq_auth_ldap",
            "version": "2.3",
            "description": "Authentication/ACL with LDAP",
            "active": false
        },
        {
            "name": "emq_auth_mongo",
            "version": "2.3",
            "description": "Authentication/ACL with MongoDB",
            "active": false
        },
        {
            "name": "emq_auth_mysql",
            "version": "2.3",
            "description": "Authentication/ACL with MySQL",
            "active": false
        },
        {
            "name": "emq_auth_pgsql",
            "version": "2.3",
            "description": "Authentication/ACL with PostgreSQL",
            "active": false
        },
        {
            "name": "emq_auth_redis",
            "version": "2.3",
            "description": "Authentication/ACL with Redis",
            "active": false
        },
        {
            "name": "emq_auth_username",
            "version": "2.3",
            "description": "Authentication with Username/Password",
            "active": false
        },
        {
            "name": "emq_coap",
            "version": "2.3",
            "description": "CoAP Gateway",
            "active": false
        },
        {
            "name": "emq_dashboard",
            "version": "2.3",
            "description": "EMQ Web Dashboard",
            "active": true
        },
        {
            "name": "emq_lua_hook",
            "version": "2.3",
            "description": "EMQ hooks in lua",
            "active": false
        },
        {
            "name": "emq_lwm2m",
            "version": "0.1",
            "description": "LWM2M Gateway",
            "active": false
        },
        {
            "name": "emq_modules",
            "version": "2.3",
            "description": "EMQ Modules",
            "active": true
        },
        {
            "name": "emq_plugin_template",
            "version": "2.3",
            "description": "EMQ Plugin Template",
            "active": false
        },
        {
            "name": "emq_recon",
            "version": "2.3",
            "description": "Recon Plugin",
            "active": true
        },
        {
            "name": "emq_reloader",
            "version": "2.3",
            "description": "Reloader Plugin",
            "active": false
        },
        {
            "name": "emq_retainer",
            "version": "2.3",
            "description": "EMQ Retainer",
            "active": true
        },
        {
            "name": "emq_sn",
            "version": "2.3",
            "description": "MQTT-SN Gateway",
            "active": false
        },
        {
            "name": "emq_stomp",
            "version": "2.3",
            "description": "Stomp Protocol Plugin",
            "active": false
        },
        {
            "name": "emq_web_hook",
            "version": "2.3",
            "description": "EMQ Webhook Plugin",
            "active": false
        }
    ]
}

Start/Stop a Plugin

Definition:

PUT /api/v2/nodes/plugins/{name}

Request parameters:

{
    "active": true/false,
}

Response:

{
    "code": 0,
    "result": []
}

List all Listeners

Definition:

GET api/v2/monitoring/listeners

Response:

{
    "code": 0,
    "result": {
        "emq@127.0.0.1": [
            {
                "protocol": "dashboard:http",
                "listen": "18083",
                "acceptors": 2,
                "max_clients": 512,
                "current_clients": 0,
                "shutdown_count": []
            },
            {
                "protocol": "mqtt:tcp",
                "listen": "127.0.0.1:11883",
                "acceptors": 16,
                "max_clients": 102400,
                "current_clients": 0,
                "shutdown_count": []
            },
            {
                "protocol": "mqtt:tcp",
                "listen": "0.0.0.0:1883",
                "acceptors": 16,
                "max_clients": 102400,
                "current_clients": 0,
                "shutdown_count": []
            },
            {
                "protocol": "mqtt:ws",
                "listen": "8083",
                "acceptors": 4,
                "max_clients": 64,
                "current_clients": 0,
                "shutdown_count": []
            },
            {
                "protocol": "mqtt:ssl",
                "listen": "8883",
                "acceptors": 16,
                "max_clients": 1024,
                "current_clients": 0,
                "shutdown_count": []
            },
            {
                "protocol": "mqtt:wss",
                "listen": "8084",
                "acceptors": 4,
                "max_clients": 64,
                "current_clients": 0,
                "shutdown_count": []
            },
            {
                "protocol": "mqtt:api",
                "listen": "127.0.0.1:8080",
                "acceptors": 4,
                "max_clients": 64,
                "current_clients": 1,
                "shutdown_count": []
            }
        ]
    }
}

List listeners of a Node

Definition:

GET api/v2/monitoring/listeners/{node_name}

Example Request:

GET api/v2/monitoring/listeners/emq@127.0.0.1

Response:

{
    "code": 0,
    "result": [
        {
            "protocol": "mqtt:api",
            "listen": "127.0.0.1:8080",
            "acceptors": 4,
            "max_clients": 64,
            "current_clients": 1,
            "shutdown_count": []
        },
        {
            "protocol": "mqtt:wss",
            "listen": "8084",
            "acceptors": 4,
            "max_clients": 64,
            "current_clients": 0,
            "shutdown_count": []
        },
        {
            "protocol": "mqtt:ssl",
            "listen": "8883",
            "acceptors": 16,
            "max_clients": 1024,
            "current_clients": 0,
            "shutdown_count": []
        },
        {
            "protocol": "mqtt:ws",
            "listen": "8083",
            "acceptors": 4,
            "max_clients": 64,
            "current_clients": 0,
            "shutdown_count": []
        },
        {
            "protocol": "mqtt:tcp",
            "listen": "0.0.0.0:1883",
            "acceptors": 16,
            "max_clients": 102400,
            "current_clients": 0,
            "shutdown_count": []
        },
        {
            "protocol": "mqtt:tcp",
            "listen": "127.0.0.1:11883",
            "acceptors": 16,
            "max_clients": 102400,
            "current_clients": 0,
            "shutdown_count": []
        },
        {
            "protocol": "dashboard:http",
            "listen": "18083",
            "acceptors": 2,
            "max_clients": 512,
            "current_clients": 0,
            "shutdown_count": []
        }
    ]
}

Messages

Publish MQTT Message

Definition:

POST api/v2/mqtt/publish

Request parameters:

{
    "topic": "test",
    "payload": "hello",
    "qos": 1,
    "retain": false,
    "client_id": "C_1492145414740"
}

Response:

{
    "code": 0,
    "result": []
}

Metrics

Get Metrics of all Nodes

Definition:

GET api/v2/monitoring/metrics/

Response:

{
    "code": 0,
    "result": {
        "emq@127.0.0.1":
        {
            "packets/disconnect":0,
            "messages/dropped":0,
            "messages/qos2/received":0,
            "packets/suback":0,
            "packets/pubcomp/received":0,
            "packets/unsuback":0,
            "packets/pingresp":0,
            "packets/puback/missed":0,
            "packets/pingreq":0,
            "messages/retained":3,
            "packets/sent":0,
            "messages/qos2/dropped":0,
            "packets/unsubscribe":0,
            "packets/pubrec/missed":0,
            "packets/connack":0,
            "messages/received":0,
            "packets/pubrec/sent":0,
            "packets/publish/received":0,
            "packets/pubcomp/sent":0,
            "bytes/received":0,
            "packets/connect":0,
            "packets/puback/received":0,
            "messages/sent":0,
            "packets/publish/sent":0,
            "bytes/sent":0,
            "packets/pubrel/missed":0,
            "packets/puback/sent":0,
            "messages/qos0/received":0,
            "packets/subscribe":0,
            "packets/pubrel/sent":0,
            "messages/qos2/sent":0,
            "packets/received":0,
            "packets/pubrel/received":0,
            "messages/qos1/received":0,
            "messages/qos1/sent":0,
            "packets/pubrec/received":0,
            "packets/pubcomp/missed":0,
            "messages/qos0/sent":0
        }
    }
}

Get Metrics of a Node

Definition:

GET api/v2/monitoring/metrics/{node_name}

Example Request:

GET api/v2/monitoring/metrics/emq@127.0.0.1

Response:

{
    "code": 0,
    "result": {
        "packets/disconnect":0,
        "messages/dropped":0,
        "messages/qos2/received":0,
        "packets/suback":0,
        "packets/pubcomp/received":0,
        "packets/unsuback":0,
        "packets/pingresp":0,
        "packets/puback/missed":0,
        "packets/pingreq":0,
        "messages/retained":3,
        "packets/sent":0,
        "messages/qos2/dropped":0,
        "packets/unsubscribe":0,
        "packets/pubrec/missed":0,
        "packets/connack":0,
        "messages/received":0,
        "packets/pubrec/sent":0,
        "packets/publish/received":0,
        "packets/pubcomp/sent":0,
        "bytes/received":0,
        "packets/connect":0,
        "packets/puback/received":0,
        "messages/sent":0,
        "packets/publish/sent":0,
        "bytes/sent":0,
        "packets/pubrel/missed":0,
        "packets/puback/sent":0,
        "messages/qos0/received":0,
        "packets/subscribe":0,
        "packets/pubrel/sent":0,
        "messages/qos2/sent":0,
        "packets/received":0,
        "packets/pubrel/received":0,
        "messages/qos1/received":0,
        "messages/qos1/sent":0,
        "packets/pubrec/received":0,
        "packets/pubcomp/missed":0,
        "messages/qos0/sent":0
    }
}

Statistics

Get Statistics of all Nodes

Definition:

GET api/v2/monitoring/stats

Example Request:

GET api/v2/monitoring/stats

Response:

{
    "code": 0,
    "result": {
        "emq@127.0.0.1":
        {
            "clients/count":0,
            "clients/max":0,
            "retained/count":0,
            "retained/max":0,
            "routes/count":0,
            "routes/max":0,
            "sessions/count":0,
            "sessions/max":0,
            "subscribers/count":0,
            "subscribers/max":0,
            "subscriptions/count":0,
            "subscriptions/max":0,
            "topics/count":0,
            "topics/max":0
        }
    }
}

Get Statistics of a Node

Definition:

GET api/v2/monitoring/stats/{node_name}

Example Request:

GET api/v2/monitoring/stats/emq@127.0.0.1

Response:

{
    "code": 0,
    "result": {
        "clients/count":0,
        "clients/max":0,
        "retained/count":0,
        "retained/max":0,
        "routes/count":0,
        "routes/max":0,
        "sessions/count":0,
        "sessions/max":0,
        "subscribers/count":0,
        "subscribers/max":0,
        "subscriptions/count":0,
        "subscriptions/max":0,
        "topics/count":0,
        "topics/max":0
    }
}

Error Code

Code Comment
0 Success
101 badrpc
102 Unknown error
103 Username or password error
104 empty username or password
105 user does not exist
106 admin can not be deleted
107 missing request parameter
108 request parameter type error
109 request parameter is not a json
110 plugin has been loaded
111 plugin has been unloaded