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:
- A valid clientId+userName+password to log into the service and get a tokenId
- Method used by default is POST
- Some services requires domain administration credentials. Others, can be used by regular users.
- 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