MQTT Broker REST API Documentation
MQTT REST API Documentation
Introduction
While building an IoT application, there is a need to control and manage the edge devices from the manager application. So, the Bevywise MQTT Route has been integrated with REST API to help you control your edge devices via the REST API. You can send messages, add new authentication keys, get client details, and do more via the API. This documentation provides a complete guide for the developers to build IoT applications using the RESTful API of MQTT Broker.
Basics
For Post
Set raw data in body.
All the parameter fields should be given as a parameter.
Once the authentication credentials you enter are verified, you will receive response. Then create authorization and set bearer token. And for all API commands except login, it is necessary to set authorization.
For GET
GET Method sends request to the server to collect data. Set the following parameters as directed.
- Key and value in header type.
- Content-type and authorization in key field.
- Value for content-type as application/json and the bearer token value.
Log-in API
This MQTT Rest API helps you to login in-to MQTT broker user interface by using username and password in “broker.conf” file.
Method:
Post:
Parameters:
PARAMETER | VALUE DETAILS |
---|---|
username | Username in broker.conf file. |
password | Password in broker.conf file. |
<ip>:8080/bwiot/api/v1/login
Response:
On Success:
{'bwapi-status-reason':'Logged in', 'bwapi-status': 'success', 'access_token': 'success'
'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyIjoiYWRtaW4ifQ.
vEqeY4rLH2JB5FCYXIhj5-ByzAHGN4tVGsNmYMaw5mg' }
Note : Access Token is used to gain authorization of APIs. They allow the user to access the APIs. When the session gets over, the user has to login again and gain the new access token to proceed further.
On Failure:
{'bwapi-status-reason': 'Invalid Login', 'bwapi-status': 'fail'}
Parameters are missing:
Clientsend
Send message to the particular client based on the client ID. This can be sent to a client that has subscribed or not subscribed to the topic.
Method:
Post:
<ip>:8080/bwiot/api/v1/send_client
Parameters:
PARAMETER | VALUE DETAIL |
---|---|
clientid | Client id or device id to which the message needs to be sent. |
topic | Publish topic to which the particular client is subscribed to. |
message | Message to be sent |
QoS | QoS Level (Optional). If not set, QoS will be 0 |
retain | Retain Flag (Optional), If not set, Retain will be 0 |
Response:
On Success:
{'bwapi-status-reason':'Message sent to client:client1','bwapi-status':'success'}
On Failure:
{'bwapi-status':'fail','bwapi-status-reason':'Message could not be delivered'}
Parameters are missing:
{'bwapi-status':'fail','bwapi-status-reason':'Authorization Credentials not provided'}
Invalid Token:
{'bwapi-status-reason':'Invalid Access Token','bwapi-status': 'fail'}
Sendall
Send message to all the devices that have subscribed to the published topic.
Method:
Post:
<ip>:8080/bwiot/api/v1/send_all
Parameters:
PARAMETER | VALUE DETAIL |
---|---|
topic | Publish topic to which the particular client is subscribed to. |
message | Message to be sent |
QoS | QoS Level (Optional). If not set, QoS will be 0 |
retain | Retain Flag (Optional), If not set, Retain will be 0 |
Response:
On Success:
{'bwapi-status-reason': 'Message sent to subscribers of topic:sensor1',
'bwapi-status': 'success'}
On Failure:
{'bwapi-status-reason':'Message could not be delivered',
'bwapi-status': 'fail'}
Parameters are missing:
{'bwapi-status': 'fail',
'bwapi-status-reason': 'Authorization Credentials not provided'}
Invalid Token:
{'bwapi-status': 'fail', 'bwapi-status-reason': 'Invalid Access Token'}
Add Authentication
Automatically add authentication credentials to MQTT Broker when authentication is enabled.
Method:
Post:
<ip>:8080/bwiot/api/v1/add_auth
Parameters:
PARAMETER | VALUE DETAIL |
---|---|
username | username to be added |
password | password to be added for the given username |
Response:
On Success:
{'status':{'bwapi-status-reason':"Added Authentication Credentials. 'highlysecure3'", 'bwapi-status': 'success'}}
On Failure:
{'status':{'bwapi-status':'fail','bwapi-status-reason':'Username already exist'}}
Parameters are missing:
{'bwapi-status': 'fail',
'bwapi-status-reason': 'Authorization Credentials not provided'}
Invalid Token:
{'bwapi-status-reason': 'Invalid Access Token', 'bwapi-status': 'fail'}
Editauth API
This API helps you to edit the previously created authentication credentials.
Method:
Post:
<ip>:8080/bwiot/api/v1/edit_auth
Parameters:
PARAMETER | VALUE DETAIL |
---|---|
username | previously created username |
new_password | new password |
Response:
On Success:
{'status':{'bwapi-status-reason':"Updated Authentication Credentials.
'highlysecure3'", 'bwapi-status': 'success'}}
On Failure:
{'status':{'bwapi-status-reason':"Failed to update Authentication Credentials. 'highlysecure4'",'bwapi-status': 'fail'}
Parameters are missing:
{'bwapi-status': 'fail',
'bwapi-status-reason': 'Authorization Credentials not provided'}
Invalid Token:
{'bwapi-status-reason': 'Invalid Access Token', 'bwapi-status': 'fail'}
Remove Authentication
Automatically remove authentication credentials to MQTT Broker when authentication is enabled.
Method:
Post:
<ip>:8080/bwiot/api/v1/remove_auth
Parameters:
PARAMETER | VALUE DETAIL |
---|---|
username | username to be removed |
password | password to be removed for the given username |
Response:
On Success:
{'status': {'bwapi-status-reason': "Removed Authentication Credentials.
'highlysecure3'", 'bwapi-status': 'success'}}
On Failure:
{'status': {'bwapi-status': 'fail',
'bwapi-status-reason': 'This username does not exist.'}}
Parameters are missing:
{'bwapi-status': 'fail',
'bwapi-status-reason': 'Authorization Credentials not provided'}
Invalid Token:
{'bwapi-status-reason': 'Invalid Access Token', 'bwapi-status': 'fail'}
Device List
List of all devices (Both active and inactive).
GET:
<ip>:8080/bwiot/api/v1/devices/
Response:
When Device Connected:
{'data': [{'device_name': 'client2', 'device_connected_time': 1653671250425, 'status': 'inactive', 'device_id': 'client2'}, {'device_name': 'client3', 'device_connected_time': 1653671245830, 'status':'active', 'device_id': 'client3'}, {'device_name': 'client1', 'device_connected_time': 1653671244824,'status': 'active', 'device_id': 'client1'}], 'page': 1.3, 'bwapi-status': 'success'}
When Device not connected :
{"bwapi-status": "fail",
"bwapi-status-reason": "No Device / Invalid Page"}
Parameters are missing:
{'bwapi-status': 'fail',
'bwapi-status-reason': 'Authorization Credentials not provided'}
Invalid Token:
{"bwapi-status": "fail",
"bwapi-status-reason": "Invalid Access Token"}
Connected Device List
List of all Connected devices.
GET:
<ip>:8080/bwiot/api/v1/connected_devices
Response:
When Device Connected:
{'bwapi-status': 'success', 'devices': {'1': 'client1', '2': 'client2'}}
or {'devices': {}, 'bwapi-status': 'success'}
Parameters are missing:
{'bwapi-status': 'fail',
'bwapi-status-reason': 'Authorization Credentials not provided'}
Invalid Token:
{'bwapi-status': 'fail', 'bwapi-status-reason': 'Invalid Access Token'}
Subscriptions
List of entire subscriptions of all the devices if the device_id parameter is not given. When the device_id parameter is given, only the subscriptions of that particular device will get listed.
GET:
<ip>:8080/bwiot/api/v1/subscriptions/
Parameter:
PARAMETER | VALUE DETAIL |
---|---|
device_id | Provide ID of the device |
Response:
When device is connected:
{'bwapi-status': 'success', 'subscriptions': [{'topic': 'sensor1',
'device_name': 'client1', 'QoS': 0,
'device_id': 'client1'}, {'topic': 'sensor1',
'device_name': 'client2', 'QoS': 0, 'device_id': 'client2'},
{'topic':'sensor2', 'device_name': 'client3', 'QoS': 0,
'device_id': 'client3'}]}
When device_id is given :
{'bwapi-status': 'success', 'subscriptions': [{'topic': 'sensor1',
'device_name': 'client2', 'QoS': 0,'device_id': 'client2'}]}
When data not found :
{"bwapi-status": "success",
"bwapi-status-reason": "no_data_found"}
Parameters are missing:
{'bwapi-status': 'fail',
'bwapi-status-reason': 'Authorization Credentials not provided'}
Invalid Token:
{"bwapi-status": "fail",
"bwapi-status-reason": "Invalid Access Token"}
Latest few Messages/Events
List of latest few number of messages/events sent by a device.
GET:
<ip>:8080/bwiot/api/v1/last_events_by_device/
Parameter:
- device_id
- limit (optional; by default – 1)
Parameters:
PARAMETER | VALUE DETAIL |
---|---|
device_id | Provide ID of the device |
limit (optional) | By default it is 1. It can be up-to 10 |
Response:
On Success when limit is 5:
{"bwapi-status": "success",
"events": [{"message": "message10","time": 1653671249195,
topic": "sensor2"},
{"message": "message9","time": 1653671248994,
"topic": "sensor2"},
{"message": "message8","time": 1653671248794,
"topic": "sensor2"},
{"message": "message7","time": 1653671248593,
"topic": "sensor2"},
{"message": "message6","time": 1653671248392,
"topic": "sensor2"}]}
When data not found :
{"bwapi-status": "success",
"bwapi-status-reason": "no_data_found"}
Parameters are missing:
{'bwapi-status': 'fail',
'bwapi-status-reason': 'Authorization Credentials not provided'}
Invalid Token:
{"bwapi-status": "fail",
"bwapi-status-reason": "Invalid Access Token"}
Latest few Commands
List of latest few number of commands/messages sent to a device.
GET:
<ip>:8080/bwiot/api/v1/last_commands_to_device/
Parameters:
PARAMETER | VALUE DETAIL |
---|---|
device_id | Provide ID of the device |
limit (optional) | By default it is 1. It can be up-to 10 |
Response:
On Success when limit is 5:
{"bwapi-status": "success",
"commands": [{"message": "message10",
"time": 1653671249195,
"topic": "sensor2"},
{"message": "message9",
"time": 1653671248995,
"topic": "sensor2"},
{"message": "message8",
"time": 1653671248794,
"topic": "sensor2"},
{"message": "message7",
"time": 1653671248594,
"topic": "sensor2"},
{"message": "message6",
"time": 1653671248393,
"topic": "sensor2"}]
When data not found :
{"bwapi-status": "success",
"bwapi-status-reason": "no_data_found"}
Parameters are missing:
{'bwapi-status': 'fail',
'bwapi-status-reason': 'Authorization Credentials not provided'}
Invalid Token:
{"bwapi-status": "fail",
"bwapi-status-reason": "Invalid Access Token"}
WILL Topic
List of WILLs of all the devices if the device_id parameter is not given. When device_id is given, only the WILL topic of that particular device will be listed.
GET:
<ip>:8080/bwiot/api/v1/wills/
Parameter:
PARAMETER | VALUE DETAIL |
---|---|
device_id | Provide ID of the device |
Response:
On Success:
{'bwapi-status': 'success', 'will': [{'message': 'wmsg1',
'device_name': 'client1', 'retain': 0, 'device_id':
'client1', 'topic': 'wtopic1', 'QoS': 0}, {'message': 'wmsg2',
'device_name': 'client2', 'retain': 0, 'device_id':
'client2', 'topic': 'wtopic2', 'QoS': 0}]}
When device_id is given :
{'bwapi-status': 'success', 'will': [{'message': 'wmsg1',
'device_name': 'client1', 'retain': 0, 'device_id':
'client1', 'topic': 'wtopic1', 'QoS': 0}]}
When data not found :
{"bwapi-status": "success",
"bwapi-status-reason": "no_data_found"}
Parameters are missing:
{'bwapi-status': 'fail',
'bwapi-status-reason': 'Authorization Credentials not provided'}
Invalid Token:
{"bwapi-status": "fail",
"bwapi-status-reason": "Invalid Access Token"}
Client Count
List of all active clients
Method:
GET:
<ip>:8080/graph/client_count
Response:
On Success:
{'bwapi-status': 'success', 'count': 2}
Parameters are missing:
{'bwapi-status': 'fail',
'bwapi-status-reason': 'Authorization Credentials not provided'}
Invalid Token:
{'bwapi-status': 'fail', 'bwapi-status-reason': 'Invalid Access Token'}
Logout
This API helps you to log out of MQTT broker user interface by using username and password in broker.conf file.
Method:
POST:
<ip>:8080/bwiot/api/v1/logout
Response:
On Success:
{'bwapi-status-reason': 'Logged Out', 'bwapi-status': 'success'}
On Failure:
Parameters Missing:
{'bwapi-status': 'fail',
'bwapi-status-reason': 'Authorization Credentials not provided'}
Invalid Token:
{'bwapi-status-reason': 'Invalid Access Token', 'bwapi-status': 'fail'}