HTTP API

The VerneMQ HTTP API is enabled by default and installs an HTTP handler on http://localhost:8888/api/v1. To read more about configuring the HTTP listener, see HTTP Listener Configuration. You can configure a HTTP listener, or a HTTPS listener to serve the HTTP API v1.
Managing API keys
The VerneMQ HTTP API uses basic authentication where an API key is passed as the username and the password is left empty. So the first step to us the HTTP API is to create an API key:
1
$ vmq-admin api-key create
2
JxctXkZ1OTVnlwvguSCE9KtujacMkOLF
Copied!
The key is persisted and available on all cluster nodes.
To list existing keys do:
1
$ vmq-admin api-key show
2
+--------------------------------+
3
|              Key               |
4
+--------------------------------+
5
|JxctXkZ1OTVnlwvguSCE9KtujacMkOLF|
6
+--------------------------------+
Copied!
To add an API key of your own choosing, do:
1
vmq-admin api-key add key=mykey
Copied!
To delete an API key do:
1
vmq-admin api-key delete key=JxctXkZ1OTVnlwvguSCE9KtujacMkOLF
Copied!
API usage
The VerneMQ HTTP API is a wrapper over the vmq-admin CLI tool, and anything that can be done using vmq-admin can be done using the HTTP API. Note that the HTTP API is therefore subject to any changes made to the vmq-admin tools and their flags & options structure. All requests are performed doing a HTTP GET and if no errors occurred an HTTP 200 OK code is returned with a possible non-empty JSON payload.
The API is using basic auth where the API key is passed as the username. An example using curl would look like this:
1
curl "http://[email protected]:8888/api/v1/session/show"
Copied!
The mapping between vmq-admin and the HTTP API is straightforward, and if one is already familiar with how the vmq-admin tool works, working with the API should be easy. The mapping works such that the command part of a vmq-admin invocation is turned into a path, and the options and flags are turned into the query string.
A mandatory parameter like the client-id in the vmq-admin session disconnect client-id=myclient command should be translated as: ?client-id=myclient.
An optional flag like --cleanup in the vmq-admin session disconnect client-id=myclient --cleanup command should be translated as: &--cleanup
Let's look at the cluster join command as an example, which looks like this:
1
vmq-admin cluster join [email protected]
Copied!
This turns into a GET request:
1
GET /api/v1/cluster/[email protected]
Copied!
To test, run it with curl:
1
curl "http://[email protected]:8888/api/v1/cluster/[email protected]"
Copied!
And the returned response would look like:
1
{
2
    "text": "Done",
3
    "type": "text"
4
}
Copied!
Below are some other examples.
Get cluster status information
Request:
1
GET /api/v1/cluster/show
Copied!
Curl:
1
curl "http://[email protected]:8888/api/v1/cluster/show"
Copied!
Response:
1
{
2
   "type" : "table",
3
   "table" : [
4
      {
5
         "Running" : true,
6
         "Node" : "[email protected]"
7
      }
8
   ]
9
}
Copied!
Retrieve session information
Request:
1
GET /api/v1/session/show
Copied!
Curl:
1
curl "http://[email protected]:8888/api/v1/session/show"
Copied!
Response:
1
{
2
   "type" : "table",
3
   "table" : [
4
      {
5
         "user" : "client1",
6
         "peer_port" : 50402,
7
         "is_online" : true,
8
         "mountpoint" : "",
9
         "client_id" : "mosq/qJpvoqe1PA4lBN1e4E",
10
         "peer_host" : "127.0.0.1"
11
      },
12
      {
13
         "user" : "client2",
14
         "is_online" : true,
15
         "peer_port" : 50406,
16
         "peer_host" : "127.0.0.1",
17
         "client_id" : "mosq/tikkXdlM28PaznBv2T",
18
         "mountpoint" : ""
19
      }
20
   ]
21
}
Copied!
List all installed listeners
Request:
1
GET /api/v1/listener/show
Copied!
Curl:
1
curl "http://[email protected]:8888/api/v1/listener/show"
Copied!
Response:
1
{
2
   "type" : "table",
3
   "table" : [
4
      {
5
         "max_conns" : 10000,
6
         "port" : "8888",
7
         "mountpoint" : "",
8
         "ip" : "127.0.0.1",
9
         "type" : "http",
10
         "status" : "running"
11
      },
12
      {
13
         "status" : "running",
14
         "max_conns" : 10000,
15
         "port" : "44053",
16
         "mountpoint" : "",
17
         "ip" : "0.0.0.0",
18
         "type" : "vmq"
19
      },
20
      {
21
         "max_conns" : 10000,
22
         "port" : "1883",
23
         "mountpoint" : "",
24
         "ip" : "127.0.0.1",
25
         "type" : "mqtt",
26
         "status" : "running"
27
      }
28
   ]
29
}
Copied!
Retrieve plugin information
Request:
1
GET /api/v1/plugin/show
Copied!
Curl:
1
curl "http://[email protected]:8888/api/v1/plugin/show"
Copied!
Response:
1
    {
2
   "type" : "table",
3
   "table" : [
4
      {
5
         "Hook(s)" : "auth_on_register\n",
6
         "Plugin" : "vmq_passwd",
7
         "M:F/A" : "vmq_passwd:auth_on_register/5\n",
8
         "Type" : "application"
9
      },
10
      {
11
         "Type" : "application",
12
         "M:F/A" : "vmq_acl:auth_on_publish/6\nvmq_acl:auth_on_subscribe/3\n",
13
         "Plugin" : "vmq_acl",
14
         "Hook(s)" : "auth_on_publish\nauth_on_subscribe\n"
15
      }
16
   ]
17
}
Copied!
Set configuration values
Request:
1
GET /api/v1/set?allow_publish_during_netsplit=on
Copied!
Curl:
1
curl "http://[email protected]:8888/api/v1/set?allow_publish_during_netsplit=on"
Copied!
Response:
1
[]
Copied!
Disconnect a client
Request:
1
GET /api/v1/session/disconnect?client-id=myclient&--cleanup
Copied!
Curl:
1
curl "http://[email protected]:8888/api/v1/session/disconnect?client-id=myclient&--cleanup"
Copied!
Response:
1
[]
Copied!

Live Administration - Previous

Managing Listeners

Next - Live Administration

Tracing

Last modified 2mo ago

Export as PDF

Copy link

Edit on GitHub

Contents

Managing API keys

API usage

Get cluster status information

Retrieve session information

List all installed listeners

Retrieve plugin information

Set configuration values

Disconnect a client