REST API

EMQX 提供了管理监控 REST API，这些 API 遵循 OpenAPI (Swagger) 3.0 规范。

EMQX 服务启动后，您可以访问 http://localhost:18083/api-docs/index.html 来查看 API 的文档。还可以直接在 Swagger UI 上尝试执行一些 API。默认情况下，Dashboard 配置下的 swagger_support 设置为 true，表示启用 Swagger UI 支持，即开启所有 swagger 相关的功能，例如生成交互式 API 文档。您也可以将它设置为 false 以禁用此功能。

本节将指导您快速开始使用 EMQX REST API。

基本路径

EMQX 在 REST API 上做了版本控制，EMQX 5.0.0 以后的所有 API 调用均以 /api/v5 开头。

认证

EMQX 的 REST API 使用 HTTP Basic 认证 携带认证凭据，您可以在 Dashboard 系统设置 -> API 密钥 界面中创建用于认证的 API 密钥，详细操作请参考 Dashboard - API 密钥。

TIP

出于安全考虑，从 EMQX 5.0.0 开始 Dashboard 用户无法用于 REST API 认证。

使用生成的 API Key 以及 Secret Key 分别作为 Basic 认证的用户名与密码，请求示例如下：

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 请求头

除非有特殊说明，绝大多数 API 要求请求头中 Accept 值设置为 application/json，响应内容将以 JSON 格式返回。

HTTP 响应状态码

EMQX 遵循 HTTP 响应状态码标准，可能的状态码如下：

状态码	描述
200	请求成功，返回的 JSON 数据将提供更多信息
201	创建成功，新建的对象将在 Body 中返回
204	请求成功，常用于删除与更新操作，Body 不会返回内容
400	请求无效，例如请求体或参数错误
401	未通过服务端认证，API 密钥过期或不存在时可能会发生
403	无权操作，检查操作对象是否正在使用或有依赖约束
404	找不到请求路径或请求的对象不存在，可参照 Body 中的 message 字段判断具体原因
409	请求的资源已存在或数量超过限制
500	服务端处理请求时发生内部错误，可通过 Body 返回内容与日志判断具体原因

分页

部分 API 支持分页，您可以通过 page（页码） 和 limit（分页大小） 参数来控制分页，分页大小最大值为 10000，如果不指定 limit 参数，则默认为 100。

例如：

GET /clients?page=1&limit=100

响应结果中 meta 字段将包含分页信息，对于使用了搜索条件的请求，EMQX 无法预知有多少条数据，因此使用 meta.hasnext 字段则表示是否还有下一页数据：

{
  "data":[],
  "meta":{
    "count":0,
    "limit":20,
    "page":1,
    "hasnext":false
  }
}

错误码

HTTP 响应状态码能够直观的判断可能存在的问题，在此基础上 EMQX 定义了一系列的错误码来标识具体的错误原因。当发生错误时，错误码将通过 Body 以 JSON 格式返回，您可以根据错误码 code 了解错误分类，根据原因 reason 了解具体的错误信息：

# GET /clients/foo

{
  "code": "RESOURCE_NOT_FOUND",
  "reason": "Client id not found"
}

错误码	描述
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