HTTP REST API

RealMQ提供了HTTP API以实现与外部系统的集成，例如发布消息和创建规则等。HTTP API服务默认监听8090端口，所有API调用以 api/v1 开头。

HTTP API 使用Basic认证和Bearer Token方式，默认的username和password是：root/123456，可以通过控制中心的用户管理进行添加和修改。

Bearer Token 方式需要先登录获取Token

响应码

HTTP 状态码 (status codes)

RealMQ 接口在调用成功时总是返回 200 OK，响应内容则以 JSON 格式返回。

可能的状态码如下：

Status Code	Description
200	成功，返回的 JSON 数据将提供更多信息
400	客户端请求无效，例如请求体或参数错误
401	客户端未通过服务端认证，使用无效的身份验证凭据可能会发生
404	找不到请求的路径或者请求的对象不存在
500	服务端处理请求时发生内部错误

Name	Type	Required	Default	Description
username	String	Required		登录用户名
password	String	Required		密码

创建产品

POST /api/v1/products

Parameters (json):

Name	Type	Required	Default	Description
name	String	Required		产品名称，唯一
type	String	Optional	1	产品类型，1直连设备，2网关
dynamic_reg	String	Optional	1	是否允许动态注册，1为允许，0为不允许
auth_type	String	Optional	1	认证类型，1秘钥认证，2证书认证(暂不支持)
description	String	Optional		产品描述

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
product_key	String
secret	String

Examples:

请求
$ curl -i --basic -u root:123456 -X POST -H "Content-Type: application/json" "http://localhost:8090/api/v1/products" -d \
'{"name":"test"}'
响应
{"data":{"secret":"59cd34daa3d78b9f","product_key":"d9c44706a4"},"code":0}

获取产品列表

GET /api/v1/products

Parameters (json):

Name	Type	Required	Default	Description
_limit	Integer	Optional	10	分页的limit
_page	Integer	Optional	1	也分的page
product_name	String	Optional		产品名称，支持模糊查询

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
meta	Object	meta Object
data	Array	product Object

meta

Name	Type	Description
page	String	分页页码
limit	String	分页条数
hasnext	Boolean	是否还有下一页
count	Integer	总数

product

Name	Type	Description
id	String	产品ID
name	String	产品名称
product_key	String	产品的Key
type	Boolean	产品类型，1直连设备，2网关
auth_type	Boolean	认证类型，1秘钥认证，2证书认证(暂不支持)
status	Integer	产品状态
dynamic_reg	Integer	是否允许动态注册，1为允许，0为不允许
device_count	Integer	产品下的设备总数
description	Integer	产品描述
create_at	Integer	产品创建时间

Examples:

请求
$ curl -i --basic -u root:123456 -X GET -H "Content-Type: application/json" "http://localhost:8090/api/v1/products"
响应
{"meta":{"page":"1","limit":"10","hasnext":false,"count":1},"data":[{"type":1,"status":1,"product_key":"0d2bf1f69d","name":"test","model_status":0,"id":1,"dynamic_reg":1,"device_count":3,"description":null,"create_at":"2025-04-22 14:45:14","auth_type":1}],"code":0}

查看产品详情

GET /api/v1/products/id

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
data	Array	product Object
product
Name	Type	Description
--------------	-------	----------------------------------------
id	String	产品ID
name	String	产品名称
product_key	String	产品的Key
product_secret	String	产品的秘钥
type	Boolean	产品类型，1直连设备，2网关
auth_type	Boolean	认证类型，1秘钥认证，2证书认证(暂不支持)
status	Integer	产品状态
dynamic_reg	Integer	是否允许动态注册，1为允许，0为不允许
device_count	Integer	产品下的设备总数
online_count	Integer	产品下的在线设备总数
offline_count	Integer	产品下的离线设备总数
description	Integer	产品描述
create_at	Integer	产品创建时间

Examples:

请求
$ curl -i --basic -u root:123456 -X GET -H "Content-Type: application/json" "http://localhost:8090/api/v1/products/${id}"
响应
{"data":[{"type":1,"status":1,"product_secret":"84b42cd9efd3e7d6","product_key":"0d2bf1f69d","online_count":1,"offline_count":0,"name":"test","model_status":0,"id":1,"dynamic_reg":1,"device_count":3,"description":null,"create_at":"2025-04-22 14:45:14","auth_type":1}],"code":0}

更新产品

PUT /api/v1/products/id

Parameters (json):

Name	Type	Required	Default	Description
name	String	Required		产品名称，唯一
type	String	Optional	1	产品类型，1直连设备，2网关
dynamic_reg	String	Optional	1	是否允许动态注册，1为允许，0为不允许
auth_type	String	Optional	1	认证类型，1秘钥认证，2证书认证(暂不支持)
description	String	Optional		产品描述

Success Response Body (JSON):

Name	Type	Description
code	Integer	0

Examples:

请求
$ curl -i --basic -u root:123456 -X PUT -H "Content-Type: application/json" "http://localhost:8090/api/v1/products/${id}" -d \
'{"name":"test1"}'
响应
{"code":0}

删除产品

DELETE /api/v1/products/id

Success Response Body (JSON):

Name	Type	Description
code	Integer	0

Examples:

请求
$ curl -i --basic -u root:123456 -X DELETE -H "Content-Type: application/json" "http://localhost:8090/api/v1/products/${id}"
响应
{"code":0}

创建设备

POST /api/v1/devices

Parameters (json):

Name	Type	Required	Description
name	String	Required	设备名称，唯一
product_key	String	Required	设备所在的产品key
username	String	Required	MQTT协议的用户名，唯一
mqtt_client_id	String	Required	MQTT协议的客户端id，唯一
nickname	String	Optional	设备昵称
password	String	Optional	设备密码，不设置系统自动生成
device_type	String	Optional	设备类型，直连设备还是子设备
description	String	Optional	设备描述

Success Response Body (JSON):

Name	Type	Description
code	Integer	0

Examples:

请求
$ curl -i --basic -u root:123456 -X POST -H "Content-Type: application/json" "http://localhost:8090/api/v1/devices" -d \
'{"name":"test", "product_key": "0d2bf1f69d", "username": "test", "mqtt_client_id": "test"}'
响应
{"code":0}

获取设备列表

GET /api/v1/devices

Parameters (json):

Name	Type	Required	Default	Description
_limit	Integer	Optional	10	分页的limit
_page	Integer	Optional	1	也分的page
product_key	String	Optional		产品key
device_name	String	Optional		设备的名称，支持模糊查询
status	String	Optional		设备状态 0 禁用 1未激活 2 离线 3在线

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
meta	Object	meta Object
data	Array	product Object

meta

Name	Type	Description
page	String	分页页码
limit	String	分页条数
hasnext	Boolean	是否还有下一页
count	Integer	总数

device

Name	Type	Description
id	Integer	设备id
name	String	设备名称
product_key	String	设备所在的产品key
username	String	MQTT协议的用户名
mqtt_client_id	String	MQTT协议的客户端id
nickname	String	设备昵称
status	Integer	设备状态 0 禁用 1未激活 2 离线 3在线
enable	Integer	是否禁用 0 禁用 1启用
ip	String	设备登录的IP地址
connected_at	String	设备本次会话上线时间
disconnected_at	String	设备本次会话离线时间
online_at	String	设备本次会话上线时长
offline_at	String	设备本次会话离线时长
description	String	设备描述
create_at	String	设备创建时间

Examples:

请求
$ curl -i --basic -u root:123456 -X GET -H "Content-Type: application/json" "http://localhost:8090/api/v1/devices"
响应
{"meta":{"page":"1","limit":"10","hasnext":false,"count":1},"data":[{"username":"test","status":1,"stats":false,"product_key":"9dc3674684","online_at":"","offline_at":"","nickname":"","name":"test","mqtt_client_id":"test","log_trace":false,"ip":null,"id":6,"enable":true,"display_username":"test","disconnected_at":"","description":null,"create_at":"2025-08-05 04:07:14","connected_at":""}],"code":0}

获取设备详情

GET /api/v1/devices/id

Success Response Body (JSON):

Name	Type	Description
code	Integer	0
data	Array	product Object

device

Name	Type	Description
id	Integer	设备id
name	String	设备名称
product_key	String	设备所在的产品key
username	String	MQTT协议的用户名
mqtt_client_id	String	MQTT协议的客户端id
nickname	String	设备昵称
status	Integer	设备状态 0 禁用 1未激活 2 离线 3在线
enable	Integer	是否禁用 0 禁用 1启用
ip	String	设备登录的IP地址
connected_at	String	设备本次会话上线时间
disconnected_at	String	设备本次会话离线时间
online_at	String	设备本次会话上线时长
offline_at	String	设备本次会话离线时长
description	String	设备描述
create_at	String	设备创建时间

Examples:

请求
$ curl -i --basic -u root:123456 -X GET -H "Content-Type: application/json" "http://localhost:8090/api/v1/devices/${id}"
响应
{"data":[{"username":"test","tags":[],"status":1,"stats":false,"shadow":{"status":0},"product_type":1,"product_key":"9dc3674684","password":"abd04e1adbd1a959c7dd41c3a581eb06","online_at":"","offline_at":"","nickname":"","name":"test","mqtt_client_id":"test","log_trace":false,"ip":null,"id":6,"enable":true,"display_username":"test","disconnected_at":"","description":null,"create_at":"2025-08-05 04:07:14","connected_at":""}],"code":0}

更新产品

PUT /api/v1/devices/id

Parameters (json):

Name	Type	Required	Description
name	String	Required	设备名称，唯一
product_key	String	Required	设备所在的产品key
username	String	Required	MQTT协议的用户名，唯一
mqtt_client_id	String	Required	MQTT协议的客户端id，唯一
nickname	String	Optional	设备昵称
password	String	Optional	设备密码，不设置系统自动生成
device_type	String	Optional	设备类型，直连设备还是子设备
description	String	Optional	设备描述

Success Response Body (JSON):

Name	Type	Description
code	Integer	0

Examples:

请求
$ curl -i --basic -u root:123456 -X PUT -H "Content-Type: application/json" "http://localhost:8090/api/v1/devices/${id}" -d \
'{"name":"test1"}'
响应
{"code":0}

删除设备

DELETE /api/v1/devices/id

Success Response Body (JSON):

Name	Type	Description
code	Integer	0

Examples:

请求
$ curl -i --basic -u root:123456 -X DELETE -H "Content-Type: application/json" "http://localhost:8090/api/v1/devices/${id}"
响应
{"code":0}

消息发布

POST /api/v1/mqtt/publish

Parameters (json):

Name	Type	Required	Default	Description
topic	String	Optional		主题，与 `topics` 至少指定其中之一
topics	String	Optional		以 `,` 分割的多个主题，使用此字段能够同时发布消息到多个主题
clientid	String	Optional		客户端标识符
payload	String	Required		消息正文
encoding	String	Optional	plain	消息正文使用的编码方式，目前仅支持 `plain` 与 `base64` 两种
qos	Integer	Optional	0	QoS 等级
retain	Boolean	Optional	false	是否为保留消息
properties	Object	Optional	{}	PUBLISH 消息里的 Property 字段

Success Response Body (JSON):

Name	Type	Description
code	Integer	0

Examples:

请求
$ curl -i --basic -u root:123456 -X POST -H "Content-Type: application/json" "http://localhost:8090/api/v1/mqtt/publish" -d \
'{"topic":"test/topic", "payload":"Hello World", "qos":1, "retain":false, "clientid":"root"}'
响应
{"code":0}

代理客户端主题订阅

Parameters (json):

Name	Type	Required	Default	Description
topic	String	Optional		主题，与 `topics` 至少指定其中之一
topics	String	Optional		以 `,` 分割的多个主题，使用此字段能够同时订阅多个主题
clientid	String	Required		客户端标识符
qos	Integer	Optional	0	QoS 等级

Success Response Body (JSON):

Name	Type	Description
code	Integer	0

Examples:

同时订阅 topic1, topic2, topic3 三个主题

$ curl -i --basic -u root:123456 -X POST -H "Content-Type: application/json" "http://localhost:8090/api/v1/mqtt/subscribe" -d '{"topics":"topic1,topic2,topic3","qos":1,"clientid":"root"}'

{"code":0}

代理客户端取消订阅

POST /api/v1/mqtt/unsubscribe

Parameters (json):

Name	Type	Required	Default	Description
topic	String	Required		主题
clientid	String	Required		客户端标识符

Success Response Body (JSON):

Name	Type	Description
code	Integer	0

Examples:

取消订阅 topic1主题

$ curl -i --basic -u root:123456 -X POST -H "Content-Type: application/json" "http://localhost:8090/api/v1/mqtt/unsubscribe" -d '{"topic":"topic1","qos":1,"clientid":"root"}'

{"code":0}

消息批量发布

POST /api/v1/mqtt/publish_batch

Parameters (json):

Name	Type	Required	Default	Description
[0].topic	String	Optional		主题，与 `topics` 至少指定其中之一
[0].topics	String	Optional		以 `,` 分割的多个主题，使用此字段能够同时发布消息到多个主题
[0].clientid	String	Optional		客户端标识符
[0].payload	String	Required		消息正文
[0].encoding	String	Optional	plain	消息正文使用的编码方式，目前仅支持 `plain` 与 `base64` 两种
[0].qos	Integer	Optional	0	QoS 等级
[0].retain	Boolean	Optional	false	是否为保留消息
[0].properties	Object	Optional	{}	PUBLISH 消息里的 properties 字段

Success Response Body (JSON):

Name	Type	Description
code	Integer	0

Examples:

$ curl -i --basic -u root:123456 -X POST -H "Content-Type: application/json" "http://localhost:8090/api/v1/mqtt/publish_batch" -d '[{"topic":"topic1","payload":"Hello World1","qos":1,"retain":false,"clientid":"root"},   {"topic":"topic2","payload":"Hello World2","qos":1,"retain":false,"clientid":"root2"}]'
{"data":[{"topic":"topic1","code":0},{"topic":"topic2","code":0}],"code":0}

主题批量订阅

Parameters (json):

Name	Type	Required	Default	Description
[0].topic	String	Optional		主题，与 `topics` 至少指定其中之一
[0].topics	String	Optional		以 `,` 分割的多个主题，使用此字段能够同时订阅多个主题
[0].clientid	String	Required		客户端标识符
[0].qos	Integer	Optional	0	QoS 等级

Success Response Body (JSON):

Name	Type	Description
code	Integer	0

Examples:

一次性订阅 topic1, topic2, topic3 三个主题

$ curl -i --basic -u root:123456 -X POST -H "Content-Type: application/json" "http://localhost:8090/api/v1/mqtt/subscribe_batch" -d '[{"topic":"topic1","qos":1,"clientid":"root1"},{"topic":"topic2","qos":1,"clientid":"root2"},{"topic":"topic3","qos":1,"clientid":"root3"}]'

{"code":0}

主题批量取消订阅

POST /api/v1/mqtt/unsubscribe_batch

Parameters (json):

Name	Type	Required	Default	Description
[0].topic	String	Required		主题
[0].clientid	String	Required		客户端标识符

Success Response Body (JSON):

Name	Type	Description
code	Integer	0

Examples:

一次性取消订阅 topic1, topic2 主题

$ curl -i --basic -u root:123456 -X POST -H "Content-Type: application/json" "http://localhost:8090/api/v1/mqtt/unsubscribe_batch" -d '[{"topic":"topic1","clientid":"root1"},{"topic":"topic2","clientid":"root2"}]'

{"code":0}

HTTP REST API ​

响应码 ​

HTTP 状态码 (status codes) ​

登录 ​

POST /api/v1/auth ​

创建产品 ​

POST /api/v1/products ​

获取产品列表 ​

GET /api/v1/products ​

查看产品详情 ​

GET /api/v1/products/id ​

更新产品 ​

PUT /api/v1/products/id ​

删除产品 ​

DELETE /api/v1/products/id ​

创建设备 ​

POST /api/v1/devices ​

获取设备列表 ​

GET /api/v1/devices ​

获取设备详情 ​

GET /api/v1/devices/id ​

更新产品 ​

PUT /api/v1/devices/id ​

删除设备 ​

DELETE /api/v1/devices/id ​

消息发布 ​

POST /api/v1/mqtt/publish ​

代理客户端主题订阅 ​

POST /api/v1/mqtt/subscribe ​

代理客户端取消订阅 ​

POST /api/v1/mqtt/unsubscribe ​

消息批量发布 ​

POST /api/v1/mqtt/publish_batch ​

主题批量订阅 ​

POST /api/v1/mqtt/subscribe_batch ​

主题批量取消订阅 ​

POST /api/v1/mqtt/unsubscribe_batch ​

HTTP REST API

响应码

HTTP 状态码 (status codes)

登录

POST /api/v1/auth

创建产品

POST /api/v1/products

获取产品列表

GET /api/v1/products

查看产品详情

GET /api/v1/products/id

更新产品

PUT /api/v1/products/id

删除产品

DELETE /api/v1/products/id

创建设备

POST /api/v1/devices

获取设备列表

GET /api/v1/devices

获取设备详情

GET /api/v1/devices/id

更新产品

PUT /api/v1/devices/id

删除设备

DELETE /api/v1/devices/id

消息发布

POST /api/v1/mqtt/publish

代理客户端主题订阅

POST /api/v1/mqtt/subscribe

代理客户端取消订阅

POST /api/v1/mqtt/unsubscribe

消息批量发布

POST /api/v1/mqtt/publish_batch

主题批量订阅

POST /api/v1/mqtt/subscribe_batch

主题批量取消订阅

POST /api/v1/mqtt/unsubscribe_batch