Connections REST API ⭐
Updated in 2.6
This page describes how to use the Connections REST API that is provided by the Management Center for the Pro Edition of Eclipse Mosquitto (MMC).
Before sending a command request, make sure that you have been authenticated.
Application Tokens REST API can be accessed only by the users with admin or connectionManager role.
Application Tokens REST API
Connections REST API features the following endpoints that allow for some CRUD operations on the connections:
GET /api/connections
- get all the connections
Example of the response:
[
{
"id": "mosquitto-dev",
"name": "Development Server",
"url": "mqtts://url.com:1883",
"credentials": {
"username": "admin",
"password": "adminpassword"
},
"ca": {
"data": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVBekNDQXV1Z0F3SUJBZ0lVQlkxaGxDR3ZkajROaEJYa1ovd...",
"endoding": "base64"
},
"cert": {
"data": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVBekNDQXV1Z0F3SUJBZ0lVQlkxaGxDR3ZkajROaEJYa1ovd...",
"endoding": "base64"
},
"key": {
"data": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVBekNDQXV1Z0F3SUJBZ0lVQlkxaGxDR3ZkajROaEJYa1ovd...",
"endoding": "base64"
},
"rejectUnauthorized": "true",
"status": {
"connected": "false",
"error": {
"code": "UNABLE_TO_VERIFY_LEAF_SIGNATURE"
}
}
},
...
]
POST /api/connections
- create a new connection
Request body must be a connection that you want to create.
Example of the request body:
{
"id": "mosquitto-dev",
"name": "Development Server",
"url": "mqtts://url.com:1883",
"credentials": {
"username": "admin",
"password": "adminpassword"
},
"ca": {
"data": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVBekNDQXV1Z0F3SUJBZ0lVQlkxaGxDR3ZkajROaEJYa1ovd...",
"endoding": "base64"
},
"cert": {
"data": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVBekNDQXV1Z0F3SUJBZ0lVQlkxaGxDR3ZkajROaEJYa1ovd...",
"endoding": "base64"
},
"key": {
"data": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUVBekNDQXV1Z0F3SUJBZ0lVQlkxaGxDR3ZkajROaEJYa1ovd...",
"endoding": "base64"
},
"rejectUnauthorized": "true"
}
Response: list of all the existing connections
Connection will not only be created but also connected by default.
A special response error of type text/plain
is 500: "Connection created but could not connect" thrown when connection has been successfully created but something went wrong, when using it to initiate a connection with a broker.
DELETE /api/connections/{connectionId}
- delete a specified connection
Path Parameters:
connectionId
- id of the connection you want to delete
Response: list of the remaining connections
Patch functionality
In case you issue POST
request to create a new connection and it returns 500: "Connection created but could not connect", you can change the body (except of course name of the connection and connection id) and issue the same POST request again. What it will do is it will patch you previously unsuccessful connection. This connection will be updated with new provided information and the Management Center will try reconnecting.
Error responses
403 - Forbidden (Connection with the same name/id already exists | Maximum number of connections reached) | User does not have access permissions
404 - Plugin not found/Not enabled
500 - An internal server error occured (special case with a
POST
request being 500: "Connection created but could not connect")