Version: Mosquitto 2.9

Connections

Connections API

Available API Paths

/api/connections
/api/connections/{connectionId}

Path: /api/connections

Methods

GET

Returns a list of active connections

Responses

Status Description Response Content or Scheme

200

List of active connections

{
  "id": {
    "type": "string",
    "description": "Connection id (must be unique)"
  },
  "name": {
    "type": "string",
    "description": "Connection text name (must be unique)"
  },
  "url": {
    "type": "string"
  },
  "credentials": {
    "type": "object",
    "properties": {
      "username": {
        "type": "string"
      },
      "password": {
        "type": "string"
      }
    }
  },
  "rejectUnauthorized": {
    "type": "boolean",
    "description": "If true will validate broker's certificate (property is considered only if TLS plugins is enabled)"
  },
  "ca": {
    "type": "object",
    "description": "CA certificate (property is considered only if TLS plugins is enabled)",
    "properties": {
      "data": {
        "description": "Encoded CA certificate",
        "type": "string"
      },
      "encoding": {
        "description": "Specifies encoding of the data property",
        "type": "string",
        "enum": [
          "base64"
        ]
      }
    }
  },
  "cert": {
    "type": "object",
    "description": "Client TLS certificate (property is considered only if TLS plugins is enabled)",
    "properties": {
      "data": {
        "description": "Encoded client certificate",
        "type": "string"
      },
      "encoding": {
        "description": "Specifies encoding of the data property",
        "type": "string",
        "enum": [
          "base64"
        ]
      }
    }
  },
  "key": {
    "type": "object",
    "description": "Client private key (property is considered only if TLS plugins is enabled)",
    "properties": {
      "data": {
        "description": "Encoded client private key",
        "type": "string"
      },
      "encoding": {
        "description": "Specifies encoding of the data property",
        "type": "string",
        "enum": [
          "base64"
        ]
      }
    }
  },
  "status": {
    "type": "object",
    "description": "Connection status of the broker",
    "required": [
      "connected",
      "timestamp"
    ],
    "properties": {
      "connected": {
        "type": "boolean",
        "description": "Specifies if the broker is currently connected"
      },
      "timestamp": {
        "type": "integer",
        "description": "Time when broker was connected to MMC"
      },
      "error": {
        "type": "object",
        "description": "Error that occured during connecting, if occured (Field is present only in case of an error)",
        "required": [
          "code"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "Error name"
          },
          "errno": {
            "type": "integer",
            "description": "Numerical id of the error"
          },
          "syscall": {
            "type": "string",
            "description": "Command that failed"
          },
          "address": {
            "type": "string",
            "description": "IP address of the broker"
          },
          "port": {
            "type": "integer",
            "description": "Port of the broker connection"
          }
        }
      }
    }
  }
} 

Example

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

Status	Description	Response Content or Scheme
401	Access to resource is denied. User not authenticated (logged in) or session expired	`{ "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Unauthorized" ], "description": "Message of the error" } }`
403	Forbidden (Connection with the same name/id already exists \| Maximum number of connections reached) \| User does not have access permissions	`{ "code": { "type": "string", "enum": [ "NOT_ALLOWED" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Not allowed", "Connection with the same name/id already exists", "Maximum number of connections reached", "Connection with either the same name or id already exists" ], "description": "Message of the error" } }`
404	Plugin is not enabled or not found	`{ "code": { "type": "string", "enum": [ "NOT_FOUND" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Plugin not found" ], "description": "Message of the error" } }`
500	An internal server error occured	`{ "code": { "type": "string", "enum": [ "NOT_ALLOWED" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "An internal server error occurred", "Connection already exists but status of the connection not found. Config file might be malformed", "Any other error message" ], "description": "Message of the error" } }`

POST

Creates a connection. Can be used by connectionManager or Admin roles. If a connection error occured on connection creation which is due to a misconfiguartion, a subsequent request with updated information might fix it

Parameters

Name Required Type Request Properties or Schema

body

true

object

A connection object.

Properties:

{
  "id": {
    "type": "string",
    "description": "Connection id (must be unique)"
  },
  "name": {
    "type": "string",
    "description": "Connection text name (must be unique)"
  },
  "url": {
    "type": "string"
  },
  "credentials": {
    "type": "object",
    "properties": {
      "username": {
        "type": "string"
      },
      "password": {
        "type": "string"
      }
    }
  },
  "rejectUnauthorized": {
    "type": "boolean",
    "description": "If true will validate broker's certificate (property is considered only if TLS plugins is enabled)"
  },
  "ca": {
    "type": "object",
    "description": "CA certificate (property is considered only if TLS plugins is enabled)",
    "properties": {
      "data": {
        "description": "Encoded CA certificate",
        "type": "string"
      },
      "encoding": {
        "description": "Specifies encoding of the data property",
        "type": "string",
        "enum": [
          "base64"
        ]
      }
    }
  },
  "cert": {
    "type": "object",
    "description": "Client TLS certificate (property is considered only if TLS plugins is enabled)",
    "properties": {
      "data": {
        "description": "Encoded client certificate",
        "type": "string"
      },
      "encoding": {
        "description": "Specifies encoding of the data property",
        "type": "string",
        "enum": [
          "base64"
        ]
      }
    }
  },
  "key": {
    "type": "object",
    "description": "Client private key (property is considered only if TLS plugins is enabled)",
    "properties": {
      "data": {
        "description": "Encoded client private key",
        "type": "string"
      },
      "encoding": {
        "description": "Specifies encoding of the data property",
        "type": "string",
        "enum": [
          "base64"
        ]
      }
    }
  }
} 

Example

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

Responses

Status Description Response Content or Scheme

200

List of all connections (active or inactive)

{
  "id": {
    "type": "string",
    "description": "Connection id (must be unique)"
  },
  "name": {
    "type": "string",
    "description": "Connection text name (must be unique)"
  },
  "url": {
    "type": "string"
  },
  "credentials": {
    "type": "object",
    "properties": {
      "username": {
        "type": "string"
      },
      "password": {
        "type": "string"
      }
    }
  },
  "rejectUnauthorized": {
    "type": "boolean",
    "description": "If true will validate broker's certificate (property is considered only if TLS plugins is enabled)"
  },
  "ca": {
    "type": "object",
    "description": "CA certificate (property is considered only if TLS plugins is enabled)",
    "properties": {
      "data": {
        "description": "Encoded CA certificate",
        "type": "string"
      },
      "encoding": {
        "description": "Specifies encoding of the data property",
        "type": "string",
        "enum": [
          "base64"
        ]
      }
    }
  },
  "cert": {
    "type": "object",
    "description": "Client TLS certificate (property is considered only if TLS plugins is enabled)",
    "properties": {
      "data": {
        "description": "Encoded client certificate",
        "type": "string"
      },
      "encoding": {
        "description": "Specifies encoding of the data property",
        "type": "string",
        "enum": [
          "base64"
        ]
      }
    }
  },
  "key": {
    "type": "object",
    "description": "Client private key (property is considered only if TLS plugins is enabled)",
    "properties": {
      "data": {
        "description": "Encoded client private key",
        "type": "string"
      },
      "encoding": {
        "description": "Specifies encoding of the data property",
        "type": "string",
        "enum": [
          "base64"
        ]
      }
    }
  },
  "status": {
    "type": "object",
    "description": "Connection status of the broker",
    "required": [
      "connected",
      "timestamp"
    ],
    "properties": {
      "connected": {
        "type": "boolean",
        "description": "Specifies if the broker is currently connected"
      },
      "timestamp": {
        "type": "integer",
        "description": "Time when broker was connected to MMC"
      },
      "error": {
        "type": "object",
        "description": "Error that occured during connecting, if occured (Field is present only in case of an error)",
        "required": [
          "code"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "Error name"
          },
          "errno": {
            "type": "integer",
            "description": "Numerical id of the error"
          },
          "syscall": {
            "type": "string",
            "description": "Command that failed"
          },
          "address": {
            "type": "string",
            "description": "IP address of the broker"
          },
          "port": {
            "type": "integer",
            "description": "Port of the broker connection"
          }
        }
      }
    }
  }
} 

Example

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

Status	Description	Response Content or Scheme
401	Access to resource is denied. User not authenticated (logged in) or session expired	`{ "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Unauthorized" ], "description": "Message of the error" } }`
403	Forbidden (Connection with the same name/id already exists \| Maximum number of connections reached) \| User does not have access permissions	`{ "code": { "type": "string", "enum": [ "NOT_ALLOWED" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Not allowed", "Connection with the same name/id already exists", "Maximum number of connections reached", "Connection with either the same name or id already exists" ], "description": "Message of the error" } }`
404	Plugin is not enabled or not found	`{ "code": { "type": "string", "enum": [ "NOT_FOUND" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Plugin not found" ], "description": "Message of the error" } }`
500	An internal server error occured	`{ "code": { "type": "string", "enum": [ "NOT_ALLOWED" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "An internal server error occurred", "Connection already exists but status of the connection not found. Config file might be malformed", "Any other error message" ], "description": "Message of the error" } }`

Path: /api/connections/{connectionId}

Methods

DELETE

Deletes a specified connection and returns a list of remaining ones. Can be used by connectionManager or Admin roles

Parameters

Name	Location	Type	Required	Description
connectionId	path	string	true	Id of the connection to be deleted

Responses

Status Description Response Content or Scheme

200

List of remaining connections (active or inactive)

{
  "id": {
    "type": "string",
    "description": "Connection id (must be unique)"
  },
  "name": {
    "type": "string",
    "description": "Connection text name (must be unique)"
  },
  "url": {
    "type": "string"
  },
  "credentials": {
    "type": "object",
    "properties": {
      "username": {
        "type": "string"
      },
      "password": {
        "type": "string"
      }
    }
  },
  "rejectUnauthorized": {
    "type": "boolean",
    "description": "If true will validate broker's certificate (property is considered only if TLS plugins is enabled)"
  },
  "ca": {
    "type": "object",
    "description": "CA certificate (property is considered only if TLS plugins is enabled)",
    "properties": {
      "data": {
        "description": "Encoded CA certificate",
        "type": "string"
      },
      "encoding": {
        "description": "Specifies encoding of the data property",
        "type": "string",
        "enum": [
          "base64"
        ]
      }
    }
  },
  "cert": {
    "type": "object",
    "description": "Client TLS certificate (property is considered only if TLS plugins is enabled)",
    "properties": {
      "data": {
        "description": "Encoded client certificate",
        "type": "string"
      },
      "encoding": {
        "description": "Specifies encoding of the data property",
        "type": "string",
        "enum": [
          "base64"
        ]
      }
    }
  },
  "key": {
    "type": "object",
    "description": "Client private key (property is considered only if TLS plugins is enabled)",
    "properties": {
      "data": {
        "description": "Encoded client private key",
        "type": "string"
      },
      "encoding": {
        "description": "Specifies encoding of the data property",
        "type": "string",
        "enum": [
          "base64"
        ]
      }
    }
  },
  "status": {
    "type": "object",
    "description": "Connection status of the broker",
    "required": [
      "connected",
      "timestamp"
    ],
    "properties": {
      "connected": {
        "type": "boolean",
        "description": "Specifies if the broker is currently connected"
      },
      "timestamp": {
        "type": "integer",
        "description": "Time when broker was connected to MMC"
      },
      "error": {
        "type": "object",
        "description": "Error that occured during connecting, if occured (Field is present only in case of an error)",
        "required": [
          "code"
        ],
        "properties": {
          "code": {
            "type": "string",
            "description": "Error name"
          },
          "errno": {
            "type": "integer",
            "description": "Numerical id of the error"
          },
          "syscall": {
            "type": "string",
            "description": "Command that failed"
          },
          "address": {
            "type": "string",
            "description": "IP address of the broker"
          },
          "port": {
            "type": "integer",
            "description": "Port of the broker connection"
          }
        }
      }
    }
  }
} 

Example

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

Status	Description	Response Content or Scheme
202	Connection was successfully created but when attempting to connect, an error occured	`{ "code": { "type": "string", "enum": [ "ACCEPTED" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Connection created but could not connect. Reason \"<error message>\"" ], "description": "Message of the error" } }`
401	Access to resource is denied. User not authenticated (logged in) or session expired	`{ "code": { "type": "string", "enum": [ "UNAUTHORIZED" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Unauthorized" ], "description": "Message of the error" } }`
403	Forbidden (Connection with the same name/id already exists \| Maximum number of connections reached) \| User does not have access permissions	`{ "code": { "type": "string", "enum": [ "NOT_ALLOWED" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Not allowed", "Connection with the same name/id already exists", "Maximum number of connections reached", "Connection with either the same name or id already exists" ], "description": "Message of the error" } }`
404	Plugin is not enabled or not found	`{ "code": { "type": "string", "enum": [ "NOT_FOUND" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "Plugin not found" ], "description": "Message of the error" } }`
500	An internal server error occured	`{ "code": { "type": "string", "enum": [ "NOT_ALLOWED" ], "description": "Name of the error" }, "message": { "type": "string", "enum": [ "An internal server error occurred", "Connection already exists but status of the connection not found. Config file might be malformed", "Any other error message" ], "description": "Message of the error" } }`

Available API Paths​

Path: /api/connections​

Methods​

GET​

POST​

Path: /api/connections/{connectionId}​

Methods​

DELETE​

Available API Paths

Path: /api/connections

Methods

GET

POST

Path: /api/connections/{connectionId}

Methods

DELETE