Skip to content

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 认证 携带 API 密钥作为认证凭据。在开始使用 EMQX REST API 之前,您需要创建 API 密钥。

TIP

出于安全考虑,从 EMQX 5.0.0 开始 Dashboard 用户无法用于 REST API 认证。 API 凭证区分角色是 EMQX 企业版中的功能。

创建 API 密钥

您可以在 Dashboard 系统设置 -> API 密钥 页面中手动创建用于认证的 API 密钥,详细操作请参考 Dashboard - API 密钥

您也可以通过 bootstrap 文件的方式创建 API 密钥。在 emqx.conf 配置文件中添加以下配置,指定文件位置:

bash
api_key = {
  bootstrap_file = "etc/default_api_key.conf"
}

在指定的文件中通过多行分割的 {API Key}:{Secret Key}:{?Role} 的格式添加多个 API 密钥:

  • API Key:任意字符串作为密钥标识。
  • Secret Key:使用随机字符串作为密钥。
  • Role (可选):指定密钥的角色,仅适用于企业版。

例如:

bash
my-app:AAA4A275-BEEC-4AF8-B70B-DAAC0341F8EB
ec3907f865805db0:Ee3taYltUKtoBVD9C3XjQl9C6NXheip8Z9B69BpUv5JxVHL:viewer
foo:3CA92E5F-30AB-41F5-B3E6-8D7E213BE97E:publisher

通过此方式创建的 API 密钥有效期为永久有效。

每次 EMQX 启动时,会将文件中设置的数据将添加到 API 密钥列表中,如果存在相同的 API Key,则将更新其 Secret Key 与 Role。

角色与权限

在 EMQX 企业版中,REST API 实现了基于角色的访问控制,API 密钥创建时,可以分配以下3个预定义的角色:

  • 管理员:此角色可以访问所有资源,未指定角色时默认使用此值。对应的角色标识为 administrator
  • 查看者:此角色只能查看资源和数据,对应于 REST API 中的所有 GET 请求。对应的角色标识为 viewer
  • 发布者:专门为 MQTT 消息发布定制,此角色仅限于访问与消息发布相关的 API。对应的角色标识为 publisher

认证方式

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

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 中,提供了分页功能,根据数据特性,有2种分页方式。

页码分页

支持分页的绝大多数 API 中,您可以通过 page(页码) 和 limit(分页大小) 参数来控制分页,分页大小最大值为 10000,如果不指定 limit 参数,则默认为 100

例如:

bash
GET /clients?page=1&limit=100

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

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

游标分页

在少数数据变化较快、页码分页效率较低的 API 中,使用游标分页的方式。

您可以通过 positioncursor(起始位置)指定数据的开始位置, limit(分页大小)指定自开始位置之后加载的数据数量。分页大小最大值为 10000,如果不指定 limit 参数,则默认为 100

例如:

bash
GET /clients/{clientid}/mqueue_messages?position=1716187698257189921_0&limit=100

响应结果中的 meta 字段将包含分页信息,meta.positionmeta.cursor 指示了下一页开始的位置:

json
{
    "meta": {
        "start": "1716187698009179275_0",
        "position": "1716187698491337643_0"
    },
    "data": [
        {
            "inserted_at": "1716187698260190832",
            "publish_at": 1716187698260,
            "from_clientid": "mqttx_70e2eecf_10",
            "from_username": "undefined",
            "msgid": "000618DD161F682DF4450000F4160011",
            "mqueue_priority": 0,
            "qos": 0,
            "topic": "t/1",
            "payload": "SGVsbG8gRnJvbSBNUVRUWCBDTEk="
        }
    ]
}

通过这种分页方式,可以高效处理数据变化较快的场景,确保数据的连续性和获取效率。

错误码

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

bash
# GET /clients/foo

{
  "code": "RESOURCE_NOT_FOUND",
  "reason": "Client id not found"
}
错误码描述
WRONG_USERNAME_OR_PWDWrong username or password
WRONG_USERNAME_OR_PWD_OR_API_KEY_OR_API_SECRETWrong username & password or key & secret
BAD_REQUESTRequest parameters not legal
NOT_MATCHConditions not matched
ALREADY_EXISTSResources already exist
BAD_CONFIG_SCHEMAConfiguration data not legal
BAD_LISTENER_IDBad listener ID
BAD_NODE_NAMEBad Node Name
BAD_RPCRPC Failed. Check the cluster status and the requested node status
BAD_TOPICTopic syntax error, topic needs to comply with the MQTT protocol standard
EXCEED_LIMITResources to be created exceed the maximum limit or minimum limit
INVALID_PARAMETERRequest parameters not legal and exceed the boundary value
CONFLICTConflicting request resources
NO_DEFAULT_VALUERequest parameters do not use default values
DEPENDENCY_EXISTSResource depends on other resources
MESSAGE_ID_SCHEMA_ERRORMessage ID parsing error
INVALID_IDBad ID schema
MESSAGE_ID_NOT_FOUNDMessage ID does not exist
NOT_FOUNDResource not found or does not exist
CLIENTID_NOT_FOUNDClient ID not found or does not exist
CLIENT_NOT_FOUNDClient not found or does not exist(usually not an MQTT client)
RESOURCE_NOT_FOUNDResource not found
TOPIC_NOT_FOUNDTopic not found
USER_NOT_FOUNDUser not found
INTERNAL_ERRORServer inter error
SERVICE_UNAVAILABLEService unavailable
SOURCE_ERRORSource error
UPDATE_FAILEDUpdate fails
REST_FAILEDReset source or configuration fails
CLIENT_NOT_RESPONSEClient not responding