While building an IoT application, there is a need to control and manage the edge devices from the manager application. So, our MQTT Broker (CrystalMQ) 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 our messaging broker. Refer our MQTT Broker integration using REST API blog to know more.
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.
Access a list of MQTT usernames along with the clients that have been granted access to each username. This helps in monitoring and managing credential usage.
GET
Example Request
Response:
On Success:
{
"status": "success",
"data": {
"credentials": [
{
"mqtt_username": "mqtt_user1",
"clients": "client1,client2"
}
]
},
"message": "MQTT Credentials and the corresponding Client Ids"
}
Unauthorized
{
"status": "error",
"message": "Unauthorized User"
}
Internal Server Error
{
"status": "error",
"message": "Failed"
}
Add new MQTT credentials or update existing ones along with the associated list of authorized clients. This operation allows you to manage and configure username-client mappings, ensuring proper access control and credential management.
Post
/crystalmq/api/v1/mqtt-credentials
{
"status": "success",
"message": "Added MQTT Credentials - MQTT Username: mqtt_user1 for
Client Id List: client1,client.,dev*"
}
Bad request - missing or invalid parameters
{
"status": "error",
"message": "Missing required parameter: mqtt_username / mqtt_password /
clients"
}
Unauthorized
{
"status": "error",
"message": "Unauthorized User"
}
Internal Server Error
{
"status": "error",
"message": "Failed"
}
Deletes all the created MQTT Credentials. This action clears all username-client mappings, effectively revoking access and ensuring that no credentials remain active.
Delete
/crystalmq/api/v1/mqtt-credentials
Response:
On Success
{
"status": "success",
"message": "Deleted MQTT Username: mqtt_user1"
}
Missing or invalid parameters
{
"status": "error",
"message": "Missing required parameter: mqtt_username"
}
Unauthorized
{
"status": "error",
"message": "Unauthorized User"
}
Internal Server Error
{
"status": "error",
"message": "Failed"
}
Obtain the Topic Access Control List (ACL) for specified Client IDs and/or MQTT Usernames. This provides detailed information on which topics each client or user is permitted to access, helping you manage topic-level permissions effectively.
/crystalmq/api/v1/acl
Response:
On Success:
{
"status": "success",
"data": {
"acl": {
"clients": {
"additionalProp1": {
"publish": {
"access": "allow",
"topics": [
"topic1",
"topic2"
]
},
"subscribe": {
"access": "allow",
"topics": [
"topic1",
"topic2"
]
}
},
"additionalProp2": {
"publish": {
"access": "allow",
"topics": [
"topic1",
"topic2"
]
},
"subscribe": {
"access": "allow",
"topics": [
"topic1",
"topic2"
]
}
},
"additionalProp3": {
"publish": {
"access": "allow",
"topics": [
"topic1",
"topic2"
]
},
"subscribe": {
"access": "allow",
"topics": [
"topic1",
"topic2"
]
}
}
},
"mqtt_username": {
"additionalProp1": {
"publish": {
"access": "allow",
"topics": [
"topic1",
"topic2"
]
},
"subscribe": {
"access": "allow",
"topics": [
"topic1",
"topic2"
]
}
},
"message": "Topic based Access Control List"
}
Bad request - missing or invalid parameters
{
"status": "error",
"message": "Missing required parameter: clientid / mqtt_username"
}
Unauthorized
{
"status": "error",
"message": "Unauthorized User"
}
Internal Server Error
{
"status": "error",
"message": "Failed"
}
Add or update the Topic Access Control List (ACL) for a Client ID or MQTT Username. Ensure that only one of mqtt_username or clientid is included in the request body.
/crystalmq/api/v1/acl
Example Value
Response:
On Success
{
"status": "success",
"message": "Updated Access Control List for Client: clientid"
}
Bad request - Either mqtt_username OR clientid must be given; but not both
{
"status": "error",
"message": "Missing required parameter: Either mqtt_username OR clientid must be
given"
}
Unauthorized - missing or invalid API token
{
"status": "error",
"message": "Unauthorized"
}
Internal Server Error
{
"status": "error",
"message": "Failed"
}
Delete the Topic Access Control List (ACL) for a Client ID or MQTT Username. Ensure that only one, either mqtt_username or clientid, is provided in the request body.
/crystalmq/api/v1/acl
Parameters:
| Name | Description |
|---|---|
| clientid <string> |
ID of the client |
Response:
On Success
{
"status": "success",
"message": "Deleted Access Control List for ClientId: mqtt_client1 if the ClientId
exists.
MQTT Username based ACL will be applied for this Client."
}
Bad request - missing or invalid parameter
{
"status": "error",
"message": "Missing required parameter: clientid"
}
Unauthorized
{
"status": "error",
"message": "Unauthorized User"
}
Internal Server Error
{
"status": "error",
"message": "Failed"
}
Obtain the total count of clients categorized by their current status. This provides a detailed overview of active, inactive, and other client states, helping in effective monitoring and management.
/crystalmq/api/v1/clients/count
Example Request
Response:
On Success
{
"status": "success",
"data": {
"active": 100,
"inactive": 50,
"all": 150
},
"message": "Number of Clients"
}
Bad requests - invalid parameters
{
"status": "error",
"message": "Invalid parameter value for status"
}
Unauthorized
{
"status": "error",
"message": "Unauthorized User"
}
Internal Server Error
{
"status": "error",
"message": "Failed"
}
Provides detailed information about a particular client. This helps in monitoring and troubleshooting individual clients by providing comprehensive insights into their activity and configuration.
/crystalmq/api/v1/clients/info
Example Request
Response:
On Success
{
"status": "success",
"data": {
"clientid": "client123",
"mqtt_version": 5,
"status": "active",
"status_timestamp": "2024-07-17T12:00:00Z",
"ip": "192.168.1.100",
"keep_alive": 60,
"clean_session": true,
"session_expiry_interval": 3600
},
"message": "Detailed information of client client123"
}
Bad requests - missing or invalid parameter
{
"status": "error",
"message": "Missing required parameter: clientid"
}
Unauthorized
{
"status": "error",
"message": "Unauthorized User"
}
Internal Server Error
{
"status": "error",
"message": "Failed"
}
Fetch the last will information for a specific MQTT client or for all clients. This provides details on the last will message set for clients, which is used to notify other clients of an unexpected disconnection.
/crystalmq/api/v1/clients/last-will
Parameters:
| PARAMETER | VALUE DETAIL |
|---|---|
| Client ID | The ID of the client for which last will information is requested. |
Example Request
Response:
When Device is Connected:
{
"status": "success",
"data": {
"client_id": {
"additionalProp1": {
"last_will": {
"topic": "last/will",
"message": "This is the last will message",
"qos": 1,
"retain": true,
"properties": {
"additionalProp1": 300,
"additionalProp2": 300,
"additionalProp3": 300
}
}
},
"additionalProp2": {
"last_will": {
"topic": "last/will",
"message": "This is the last will message",
"qos": 1,
"retain": true,
"properties": {
"additionalProp1": 300,
"additionalProp2": 300,
"additionalProp3": 300
}
}
},
"message": "Last Will of Client(s)"
}
Bad request - missing or invalid paremeter
{
"status": "error",
"message": "Failed to retrieve last will information"
}
Unauthorized
{
"status": "error",
"message": "Unauthorized User"
}
Internal Server Error
{
"status": "error",
"message": "Failed"
}
Disconnects a particular MQTT5 client. This action terminates the client's current session, stopping any ongoing communications and freeing up resources.
/crystalmq/api/v1/clients/disconnect
Response:
On Success when limit is 5:
{
"status": "success",
"message": "Disconnected the Client: client123"
}
Bad request - missing or invalid parameter
{
"status": "error",
"message": "Missing required parameter: clientid"
}
Unauthorized
{
"status": "error",
"message": "Unauthorized User"
}
Internal Server Error
{
"status": "error",
"message": "Failed"
}
Fetch the list of subscriptions for all clients or for a specific client when a client ID is provided. This allows you to view which topics each client is subscribed to, aiding in subscription management.
/crystalmq/api/v1/clients/subscriptions
Parameters:
| PARAMETER | VALUE DETAIL |
|---|---|
| client id | The ID of the client whose subscriptions are to be retrieved. |
Example Request
Response:
On Success
{
"status": "success",
"data": {
"clients": {
"additionalProp1": {
"subscriptions": [
{
"filter": "topic/filter",
"qos": 1,
"subscription_options": {
"subscription_identifier": 1,
"user_property": "property_value",
"no_local": true,
"retain_handling": 0,
"retain_as_published": 1
}
}
]
},
"additionalProp2": {
"subscriptions": [
{
"filter": "topic/filter",
"qos": 1,
"subscription_options": {
"subscription_identifier": 1,
"user_property": "property_value",
"no_local": true,
"retain_handling": 0,
"retain_as_published": 1
}
}
]
},
"message": "Client subscriptions"
}
Bad request - missing or invalid parameter
{
"status": "error",
"message": "Missing required parameter: clientid"
}
Unauthorized
{
"status": "error",
"message": "Unauthorized User"
}
Internal Server Error
{
"status": "error",
"message": "Failed"
}
Obtain a comprehensive list of clients categorized by their current status. This retrieval provides insight into client activity and status, helping you monitor and manage client connections effectively.
/crystalmq/api/v1/clients
Response:
On Success
{
"status": "success",
"data": {
"active": [
"client1",
"client2"
],
"inactive": [
"client3",
"client4"
]
},
"message": "Client Ids"
}
Bad request - invalid parameter
{
"status": "error",
"message": "Invalid parameter value for status"
}
Unauthorized
{
"status": "error",
"message": "Unauthorized User"
}
Internal Server Error
{
"status": "error",
"message": "Failed"
}
Fetch a list of clients currently subscribed to a specific MQTT topic. This provides insights into which clients are receiving messages from the topic.
/crystalmq/api/v1/topics/subscriptions
Example Request
Response:
On Success
{
"status": "success",
"data": {
"clients": {
"additionalProp1": {
"filter": "topic/filter",
"qos": 1,
"subscription_options": {
"subscription_identifier": 1,
"user_property": "property_value",
"no_local": true,
"retain_handling": 0,
"retain_as_published": 1
}
},
"additionalProp2": {
"filter": "topic/filter",
"qos": 1,
"subscription_options": {
"subscription_identifier": 1,
"user_property": "property_value",
"no_local": true,
"retain_handling": 0,
"retain_as_published": 1
}
},
"message": "Clients subscribed to topic"
}
Bad requests - missing or invalid parameters
{
"status": "error",
"message": "Missing required parameter: topic"
}
Unauthorized
{
"status": "error",
"message": "Unauthorized User"
}
Internal Server Error
{
"status": "error",
"message": "Failed"
}
Access the latest events recorded by the broker, offering insights into recent activities and system interactions. This feature helps monitor current event trends and troubleshoot any issues promptly.
/crystalmq/api/v1/recent-events
Example Request
Response:
On Success
{
"status": "success",
"data": [
{
"client": "client001",
"topic": "/devices/+/data",
"event": "Event data here",
"timestamp": "2024-07-17T14:30:00Z",
"properties": {
"qos": 1
}
}
],
"message": "Event(s) received from Client(s)"
}{
"status": "success",
"data": [
{
"client": "client001",
"topic": "/devices/+/data",
"event": "Event data here",
"timestamp": "2024-07-17T14:30:00Z",
"properties": {
"qos": 1
}
}
],
"message": "Event(s) received from Client(s)"
}
Bad request due to missing or invalid data
{
"status": "error",
"message": "Missing required parameter: topic"
}
Unauthorized
{
"status": "error",
"message": "Unauthorized"
}
Internal Server Error
{
"status": "error",
"message": "Failed"
}
Fetch a list of the most recent commands sent to clients. This feature provides insights into recent command activities, helping you track and review client interactions effectively.
/crystalmq/api/v1/recent-commands
Response:
On Success
{
"status": "success",
"data": [
{
"client": "client001",
"topic": "/devices/+/data",
"command": "GET",
"timestamp": "2024-07-17T14:30:00Z",
"properties": {
"qos": "1"
}
}
]
}
Bad request due to missing or invalid data
Parameters are missing:
{
"status": "error",
"message": "Missing required parameter: topic"
}
Unauthorized
{
"status": "error",
"message": "Unauthorized"
}
Internal Server Error
{
"status": "error",
"message": "Failed"
}
Send a command to a specific client by publishing it to a designated topic. This action allows you to remotely control or instruct clients based on their subscribed topics.
/crystalmq/api/v1/send-command
Example Request
Response:
On Success
{
"status": "success",
"message": "Command sent to the Client: client123"
}
Bad request due to missing or invalid data
Parameters are missing:
{
"status": "error",
"message": "Missing required parameter: clientid / topic"
}
Unauthorized
{
"status": "error",
"message": "Unauthorized"
}
Internal Server Error
{
"status": "error",
"message": "Failed"
}