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. To know about MQTT Broker integration using REST API , refer our blog.
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.
GET Method sends request to the server to collect data. Set the following parameters as directed.
This MQTT Rest API helps you to login in-to MQTT broker user interface by using username and password in “broker.conf” file.
POST
Parameters:
| PARAMETER | VALUE DETAILS |
|---|---|
| username | Username in broker.conf file. |
| password | Password in broker.conf file. |
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.
{'bwapi-status-reason': 'Invalid Login', 'bwapi-status': 'fail'}
{'bwapi-status':'fail','bwapi-status-reason':'Missing parameter:password'}
Authorization header is the method of providing authentication information. All the APIs below are accessing specific data to a user who is logged-in to the MQTT broker. So, we need to provide the session token to all the APIs. The Session token should be set as a part of the Request Header to provide authentication information. The format of the Authorization header is
Authorization: < Access Token>
Error Responses On using Authorization Header:
If Authorization header is not defined
{
"detail": "Authentication credentials were not provided."
}
If Token is Invalid
{
"detail": "Invalid token."
}
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.
POST
<ip>:8080/bwiot/api/v1/send_client
| PARAMETER | VALUE DETAILS |
|---|---|
| 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 |
{'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'}
Send message to all the devices that have subscribed to the published topic.
POST
<ip >:8080/bwiot/api/v1/send_all
Parameters:
| PARAMETER | VALUE DETAILS |
|---|---|
| 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'}
Automatically add authentication credentials to MQTT Broker when authentication is enabled.
<ip>:8080/bwiot/api/v1/add_auth
Parameters:
| PARAMETER | VALUE DETAILS |
|---|---|
| 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'}
This API helps you to edit the previously created authentication credentials.
<ip>:8080/bwiot/api/v1/edit_auth
Parameters:
| PARAMETER | VALUE DETAILS |
|---|---|
| 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'}
Automatically remove authentication credentials to MQTT Broker when authentication is enabled.
<ip>:8080/bwiot/api/v1/remove_auth
Parameters:
| PARAMETER | VALUE DETAILS |
|---|---|
| username | username to be removed |
| password | password to be removed for the given username (Optional) |
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'}
List of all devices (Both active and inactive).
<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 :
{'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": "fail", "bwapi-status-reason": "Invalid Access Token"}
List of all Connected devices.
<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'}
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.
<ip>:8080/bwiot/api/v1/subscriptions
Parameters:
| 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 Device not connected :
{"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"}
List of latest few number of messages/events sent by a device.
<ip>:8080/bwiot/api/v1/last_events_by_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",
"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 Device 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"}
List of latest few number of commands/messages sent to a device.
<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 Device 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"}
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.
<ip>:8080/bwiot/api/v1/wills
Parameters:
| PARAMETER | VALUE DETAIL |
|---|---|
| device_id | Provide ID of the device |
Response:
On Success when limit is 5:
{'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}]}
{'bwapi-status': 'success', 'will': [{'message': 'wmsg1',
'device_name': 'client1', 'retain': 0, 'device_id':
'client1', 'topic': 'wtopic1', 'QoS': 0}]}
When Device 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"}
List of all active clients
<ip>:8080/graph/client_count
Response:
On Success when limit is 5:
{'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'}
This API helps you to log out of MQTT broker user interface by using username and password in broker.conf file.
<ip>:8080/bwiot/api/v1/logout
Response:
On Success
{'bwapi-status-reason': 'Logged Out', 'bwapi-status': 'success'}
Failed
Parameters are missing:
{'bwapi-status': 'fail', 'bwapi-status-reason': 'Authorization Credentials not provided'}
Invalid Token:
{'bwapi-status-reason': 'Invalid Access Token', 'bwapi-status': 'fail'}