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. To know about MQTT Broker integration using REST API , refer our blog.

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

:8080/bwiot/api/v1/login

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.

On Failure:

{'bwapi-status-reason': 'Invalid Login', 'bwapi-status': 'fail'}

Parameters are missing:

{'bwapi-status':'fail','bwapi-status-reason':'Missing parameter:password'}

Authorization Header

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."
}

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 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
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 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'}

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 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'}

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 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'}

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 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'}

Device List

List of all devices (Both active and inactive).

Method:
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 :

{'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"}

Connected Device List

List of all Connected devices.

Method:
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.

Method:
GET

<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"}

Latest few Messages/Events

List of latest few number of messages/events sent by a device.

Method:
GET

<ip>:8080/bwiot/api/v1/last_events_by_device

Parameters:

  • device_id
  • limit (optional; by default – 1)

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"}

Latest few Commands

List of latest few number of commands/messages sent to a device.

Method:
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 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"}

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.

Method:
GET

<ip>:8080/bwiot/api/v1/wills

Parameters:

  • device_id
  • limit (optional; by default – 1)

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"}

Client Count

List of all active clients

Method:
GET

<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'}

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'}

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'}