REST API

REST API

EMQX exposes an HTTP management API designed following OpenAPI (Swagger) 3.0 specification.

After EMQX is started, you can visit http://localhost:18083/api-docs/index.html (opens new window) to view the API document, and also execute the management APIs from this UI.

The section will introduce how to work with EMQX REST API.

Basic Path

EMQX has version control on the REST API, all API paths from EMQX 5.0.0 start with /api/v5.

Authentication

EMQX’s REST API uses HTTP Basic Authentication (opens new window).

To create an API key, you can click System -> API Key page on the left navigation menu of the Dashboard, Please refer to Dashboard - API Keys.

You can use the generated API Key and Secret Key as the username and password for Basic authentication:

curl -X GET http://localhost:18083/api/v5/nodes \
     -u 4f33d24d7b8e448d:gwtbmFJZrnzUu8mPK1BxUkBA66PygETiDEegkf1q8dD \
     -H "Content-Type: application/json"
``` ```
import okhttp3.*;

import java.io.IOException;

public class EMQXNodesAPIExample {
    public static void main(String[] args) {
        try {
            String username = "4f33d24d7b8e448d";
            String password = "gwtbmFJZrnzUu8mPK1BxUkBA66PygETiDEegkf1q8dD";

            OkHttpClient client = new OkHttpClient();

            Request request = new Request.Builder()
                    .url("http://localhost:18083/api/v5/nodes")
                    .header("Content-Type", "application/json")
                    .header("Authorization", Credentials.basic(username, password))
                    .build();

            Response response = client.newCall(request).execute();
            System.out.println(response.body().string());
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}
``` ```
import urllib.request
import json
import base64

username = '4f33d24d7b8e448d'
password = 'gwtbmFJZrnzUu8mPK1BxUkBA66PygETiDEegkf1q8dD'

url = 'http://localhost:18083/api/v5/nodes'

req = urllib.request.Request(url)
req.add_header('Content-Type', 'application/json')

auth_header = "Basic " + base64.b64encode((username + ":" + password).encode()).decode()
req.add_header('Authorization', auth_header)

with urllib.request.urlopen(req) as response:
    data = json.loads(response.read().decode())

print(data)
``` ```
package main

import (
    "fmt"
    "net/http"
    "bytes"
    "encoding/json"
)

func main() {
    username := "4f33d24d7b8e448d"
    password := "gwtbmFJZrnzUu8mPK1BxUkBA66PygETiDEegkf1q8dD"

    url := "http://localhost:18083/api/v5/nodes"

    req, err := http.NewRequest("GET", url, nil)
    if err != nil {
        panic(err)
    }
    req.SetBasicAuth(username, password)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    buf := new(bytes.Buffer)
    _, err = buf.ReadFrom(resp.Body)
    if err != nil {
        panic(err)
    }

    var data interface{}
    json.Unmarshal(buf.Bytes(), &data)
    fmt.Println(data)
}
``` ```
const axios = require('axios')

const username = '4f33d24d7b8e448d'
const password = 'gwtbmFJZrnzUu8mPK1BxUkBA66PygETiDEegkf1q8dD'

axios
  .get('http://localhost:18083/api/v5/nodes', {
    auth: {
      username: username,
      password: password,
    },
    headers: {
      'Content-Type': 'application/json',
    },
  })
  .then((response) => {
    console.log(response.data)
  })
  .catch((error) => {
    console.log(error)
  })

HTTP Headers

Unless otherwise specified, most API requests require the Accept header to be set to application/json, and then the response will be returned in JSON format.

HTTP Response Status Code

EMQX follows the HTTP Response Status Code (opens new window) standard, and the possible status codes are as follows:

Error Codes

Besides the HTTP response status codes, EMQX also defines a list of error codes to identify specific errors.

When an error happens, the error code is returned in JSON format by the Body:

```

GET /clients/foo

{ "code": "RESOURCE_NOT_FOUND", "reason": "Client id not found" } ``` Error Codes| Description
---|---
WRONG_USERNAME_OR_PWD| Wrong username or password
WRONG_USERNAME_OR_PWD_OR_API_KEY_OR_API_SECRET| Wrong username & password or key & secret
BAD_REQUEST| Request parameters not legal
NOT_MATCH| Conditions not matched
ALREADY_EXISTS| Resources already exist
BAD_CONFIG_SCHEMA| Configuration data not legal
BAD_LISTENER_ID| Bad listener ID
BAD_NODE_NAME| Bad Node Name
BAD_RPC| RPC Failed. Check the cluster status and the requested node status
BAD_TOPIC| Topic syntax error, topic needs to comply with the MQTT protocol standard
EXCEED_LIMIT| Resources to be created exceed the maximum limit or minimum limit
INVALID_PARAMETER| Request parameters not legal and exceed the boundary value
CONFLICT| Conflicting request resources
NO_DEFAULT_VALUE| Request parameters do not use default values
DEPENDENCY_EXISTS| Resource depends on other resources
MESSAGE_ID_SCHEMA_ERROR| Message ID parsing error
INVALID_ID| Bad ID schema
MESSAGE_ID_NOT_FOUND| Message ID does not exist
NOT_FOUND| Resource not found or does not exist
CLIENTID_NOT_FOUND| Client ID not found or does not exist
CLIENT_NOT_FOUND| Client not found or does not exist(usually not an MQTT client)
RESOURCE_NOT_FOUND| Resource not found
TOPIC_NOT_FOUND| Topic not found
USER_NOT_FOUND| User not found
INTERNAL_ERROR| Server inter error
SERVICE_UNAVAILABLE| Service unavailable
SOURCE_ERROR| Source error
UPDATE_FAILED| Update fails
REST_FAILED| Reset source or configuration fails
CLIENT_NOT_RESPONSE| Client not responding