Skip to content

MQTT

MQTT REST gives user the possiblity to manage MQTT instances. All instances created are available immediately after creation. Every user can access only his own MQTT instance(s) and dedicated topic(s).

Get all MQTT instances

URL : https://api.iotaap.io/v1/mqtt

Method : GET

Auth required : YES

URL Params

  • search_value (string): filtering value string (filtering by user parameter)
  • offset (number): number of records to skip
  • limit (number): number of records to return
  • draw (string): value will be returned back in the response
  • order_dir (string): asc/desc

Success Response

Code : 200 OK

Response example

{
    "mqtts": [
        {
            "_id": "5e23585e02180144b6dcbb05",
            "server": "mqtt.iotaap.io",
            "user": "Hcixd1Fx",
            "password": "09RwX8S5aQET",
            "port": "8883",
            "owner": "5e10fc5e77ba18070312e171",
            "created_at": "2020-01-18T19:11:26.413Z",
            "__v": 0
        },
        {
            "_id": "5e245a5153f26101dbf382d8",
            "server": "mqtt.iotaap.io",
            "user": "Z3sT65kb",
            "password": "eNb1wBtdK7im",
            "port": "8883",
            "owner": "5e10fc5e77ba18070312e171",
            "created_at": "2020-01-19T13:32:01.259Z",
            "__v": 0
        }
    ],
    "recordsTotal": 21,
    "recordsFiltered": 2,
    "draw": "warp"
}

Response Params

  • mqtts (array): array of MQTT objects
  • recordsTotal (number): total number of records (MQTT instances)
  • recordsFiltered (number): number of records that match given filter
  • draw (string): draw string from request

Error Response

Condition : If MQTT instance resources are not available at the moment

Code : 500 INTERNAL SERVER ERROR

Content :

{
    "message": "Error when getting MQTT instances",
    "error": "<Error information>"
}

Get specific MQTT instance

URL : https://api.iotaap.io/v1/mqtt/{mqtt-id}

Method : GET

Auth required : YES

Path Params

  • {mqtt-id} (string): specific MQTT instance ID

URL example

https://api.iotaap.io/v1/mqtt/5e23585e02180144b6dcbb05

Success Response

Code : 200 OK

Response example

{
    "_id": "5e23585e02180144b6dcbb05",
    "server": "mqtt.iotaap.io",
    "user": "Hcixd1Fx",
    "password": "09RwX8S5aQET",
    "port": "8883",
    "owner": "5e10fc5e77ba18070312e171",
    "created_at": "2020-01-18T19:11:26.413Z",
    "__v": 0
}

Error Response

Condition : If MQTT instance does not exist or current user is not the owner

Code : 404 NOT FOUND

Content :

{
    "message": "No such MQTT instance"
}

Condition : If MQTT instance resources are not available at the moment

Code : 500 INTERNAL SERVER ERROR

Content :

{
    "message": "Error when getting MQTT instance",
    "error": "<Error information>"
}

Create new MQTT instance

System will automatically generate new MQTT instance credentials if there are available MQTT instances in the current billing plan

URL : https://api.iotaap.io/v1/mqtt

Method : POST

Auth required : YES

Instance credentials

All instance credentials are generated by our system, and cannot be changed.

Success Response

Code : 201 CREATED

Response example

{
    "_id": "5e278fecb702e4121e7aefa6",
    "server": "mqtt.iotaap.io",
    "user": "CZpgrCvQ",
    "password": "HdP7QTuqwF8Z",
    "port": "8883",
    "owner": "5e10fc5e77ba18070312e171",
    "created_at": "2020-01-21T23:57:32.810Z",
    "__v": 0
}

Response Params

  • _id (string): new instance unique ID
  • server (string): MQTT server endpoint
  • user (string): username to be used when connecting to the instance
  • password (string): password to be used when connecting to the instance
  • port (string): port to be used when connecting to the endpoint
  • owner (string): your user ID (just for the reference)
  • created_at (string): timestamp of instance creation

Error Responses

Condition : If number of MQTT instances reached the maximum number of allowed instances in currently active billing model

Code : 403 FORBIDDEN

Content :

{
    "message": "Maximum number of MQTT instances reached. Please upgrade your account."
}

Condition : If there was an issue with MQTT instance creation

Code : 500 INTERNAL SERVER ERROR

Content :

{
    "message": "Error when creating MQTT instance",
    "error": "<Error information>"
}

Remove MQTT instance

Irreversible process

When MQTT instance is removed, all access credentials will be removed, as well as any acitve topic(s). All topics and transport data will stop working immediately. Be aware that this is irreversible process and you will not be able to get same access credentials again.

URL : https://api.iotaap.io/v1/mqtt/{mqtt-id}

Method : DELETE

Auth required : YES

Path Params

  • {mqtt-id} (string): specific MQTT instance ID

URL example

https://api.iotaap.io/v1/mqtt/5e278fecb702e4121e7aefa6

Success Response

Code : 200 OK

Response example

{
    "message": "'MQTT instance succesfully removed"
}

Error Responses

Condition : If MQTT instance doesn't exist or current user is not the owner

Code : 404 NOT FOUND

Content :

{
    "message": "No such MQTT instance"
}

Condition : If there was an issue with removing the instance

Code : 500 INTERNAL SERVER ERROR

Content :

{
    "message": "Error when removing MQTT instance",
    "error": "<Error information>"
}

Condition : If there was a problem with fetching user data on MQTT server

Code : 500 INTERNAL SERVER ERROR

Content :

{
    "message": "Error finding instance user"
}