REST API to manage MQTT service (ReactiveMyQtt v1.0.17)

Next you will find description for REST API available to your service.
To interface with it you will need:

  1. A valid clientId+userName+password to log into the service and get a tokenId
  2. Method used by default is POST
  3. Some services requires domain administration credentials. Others, can be used by regular users.
  4. All message bodies are encoded using Json

Login into the API and getting a tokenId

Service: POST /login
Message: {‘clientId’ : string, ‘userName’ : string, ‘password’ : string, ‘cleanSession’ : boolean }

Example:

>>curl -X POST https://node02.myqtthub.com/login -d '{"clientId" : "testId", "userName" : "aUserName", "password" : "test1234", "cleanSession" : false }'

If login fails, 200 OK code is received with body:

Service denied (auth login failure, wrong password, identifier rejected or connection refused)

If login succeed, 200 OK code is received with body example:

{“tokenId”:”0da82260-207e-4e4e-9fc3-d2846d7c54f0″,”stamp”:1531410287,”validUntil”:1531494887}

You will have to use this “tokenId” for the rest of the service. You will have to send it as a cookie and as a parameter.

Logout from the API (canceling tokenId)

Service: POST /logout
Message: {‘tokenId’ : string }
Cookie: TokenId

Example:

curl --cookie "tokenId=0da82260-207e-4e4e-9fc3-d2846d7c54f0" -X POST https://node02.myqtthub.com/logout -d '{"tokenId" : "0da82260-207e-4e4e-9fc3-d2846d7c54f0"}'

If logout succeed, 200 Ok code is received with body example:

Logout completed

If logout fails, 400 Bad request is received with body example:

Failed to complete request, error was: java.lang.Exception: Authentication failure, failed to complete operation, error was: Token not valid, expired or login session needed

Change my password (for a logged device)

Service: POST /change-my-password
Message: {‘newPassword : string, ‘tokenId’ : tokenId}
Cookie: TokenId

Service result:
Correct finalization: 200 OK
Failure: 400 Bad request

Get user information (for a logged device)

Service: POST /user/info
Message: {‘tokenId’ : tokenId}
Cookie: TokenId

Returns session information associated to loggedu ser.

Service result:
Correct finalization: 200 OK {‘clientId’ : string, ‘ip’ : string, ‘userName’ : string, ‘domainName’ : string, ‘isAdmin’ : boolean, ‘hasDomainAdmin’ : boolean, ‘cleanSession’ : boolean}
Failure: 400 Bad request

Get connected devices to your domain (for a logged domain admin device)

Service: POST /devices/connected
Message: {‘tokenId’ : tokenId}
Cookie: TokenId

Returns a list of devices connected. Needs tokenId for a domain admin valid user.

Service result:
Correct finalization: 200 OK [{‘clientId’}, {‘clientId2’}…]
Failure: 400 Bad request

List domains (MyQtt contexts) (for a logged domain admin device)

Service: POST /domain/list
Message: {‘tokenId’ : tokenId}
Cookie: TokenId

Returns a list of all domains for which the user has domain administration rights

Service result:
Correct finalization: 200 OK [[name, plan, active], [next-domain], …]
Failure: 400 Bad request

List devices (for a domain) (for a logged domain admin device)

Service: POST /device/list
Message: {‘domainName’ : string, ‘tokenId’ : tokenId}
Cookie: TokenId

Returns the list of devices registered into the given domain.

Service result:
Correct finalization: 200 OK [[clientId, userName, active], [next-device], …]
Failure: 400 Bad request

Add device (to a domain) (for a logged domain admin device)

Service: POST /device/add
Message: {‘domainName’ : string, ‘clientId’ : string, userName : string, ‘password’ : string, ‘tokenId’ : tokenId}
Cookie: TokenId

Creates a new device.

Service result:
Correct finalization: 200 OK device created
Failure: 400 Bad request

Remove device (from a domain) (for a logged domain admin device)

Service: POST /device/remove
Message: {‘domainName’ : string, ‘clientId’ : string, userName : string, ‘tokenId’ : tokenId}
Cookie: TokenId

Removes a new device.

Service result:
Correct finalization: 200 OK device removed
Failure: 400 Bad request

List allowed ips for current logged device

Service: POST /ip/allowed/list
Message: {‘tokenId’ : tokenId}
Cookie: TokenId

Allows to list ips for which this device is allowed to log in. If no ip is registered, this device is allowed to login from any IP. After the first ip is added, the platforms starts limiting logins for this service. Current login is not limited by this service.

Service result:
Correct finalization: 200 OK [[ip active], [next-ip], …]
Failure: 400 Bad request

Add allowed ip for current logged device

Service: POST /ip/allowed/add
Message: {‘remoteAddr’ : string, ‘tokenId’ : tokenId}
Cookie: TokenId

Allows to add a new remoteAddr IP to allow login for current logged device.

Service result:
Correct finalization: 200 OK ip added
Failure: 400 Bad request

Remove allowed ip for current logged device

Service: POST /ip/allowed/remove
Message: {‘remoteAddr’ : string, ‘tokenId’ : tokenId}
Cookie: TokenId

Allows to remove remoteAddr IP to allow login for current logged device. If all ips
are removed, this device can login from any ip.

Service result:
Correct finalization: 200 OK ip removed
Failure: 400 Bad request

Subscribe topic for current logged device

Service: POST /subscribe
Message: {‘subscriptions’ : [[string, int], [next-subscribe]..], ‘tokenId’ : tokenId}
Cookie: TokenId

Each position for the list includes a [topicToSubscribe, qosToSubscribe]

Allows to subscribe to a list of topics for current logged device.

Service returns allowed subscription codes.

Service result:
Correct finalization: 200 OK [int, …]
Failure: 400 Bad request

Unsubscribe topic for current logged device

Service: POST /unsubscribe
Message: {‘subscriptions’ : [string, ..], ‘tokenId’ : tokenId}
Cookie: TokenId

Service receives a list of topics to unsubscribe

Service result:
Correct finalization: 200 OK
Failure: 400 Bad request

Get current subscriptions for current logged device

Service: POST /get-subscriptions
Message: {‘tokenId’ : tokenId}
Cookie: TokenId

Service receives the list of subscriptions that has this device.

Service result:
Correct finalization: 200 OK
Failure: 400 Bad request

Publish message for a current logged device

Service: POST /publish
Message: {‘topic’ : string, ‘qos’ : int, ‘payload’ : string, ‘retain’ : boolean, ‘dup’ : boolean, ‘tokenId’ : tokenId}
Cookie: TokenId

Allows to PUBLISH a message with the provided data. Payload is a base64
payload with the message to publish. Platform unpacks it before sending
to subscribers.

Service result:
Correct finalization: 200 OK
Failure: 400 Bad request

Pull messages for a current logged device

Service: POST /pull
Message: {‘tokenId’ : tokenId}
Cookie: TokenId

Allows to pull (receive) all messages that were received since last pull.

Service result:
Correct finalization: 200 OK [{‘topic’ : string, ‘qos’ : int, ‘payload’ : string, ‘retain’ : false, ‘dup’ : boolean}, ..]
Failure: 400 Bad request