Table of contents
1. Intro: login and logout
1.1) REST API to manage MQTT service (ReactiveMyQtt v6.7.764
1.2) Login into the API and getting a tokenId
1.3) Logout from the API (cancelling tokenId)
2. User management
2.1) Change my password (for a logged device)
2.2) Get user information (for a logged device)
2.3) Get connected devices to your domain (for a logged domain admin device)
3. Domain and device management
3.1) Get connected devices to your domain (for a logged domain admin device)
3.2) List domains (MyQtt contexts) (for a logged domain admin device)
3.3) List devices (for a domain) (for a logged domain admin device)
3.4) Add device (to a domain) (for a logged domain admin device)
3.5) Remove device (from a domain) (for a logged domain admin device)
4. IP security
4.1) List allowed ips for current logged device
4.2) Add allowed ip for current logged device
4.3) Remove allowed ip for current logged device
5. Subscription management
5.1) Subscribe topic for current logged device
5.2) Unsubscribe topic for current logged device
5.3) Get current subscriptions for current logged device
5.4) List domain subscriptions
5.5) Administrative/domain subscribe
5.6) Administrative/domain unsubscribe
6.Publishing and getting messages
6.1) Publish message for a current logged device
6.2) Pull messages for a current logged device
7.Handling filters
7.1) List filters
7.2) Create filter
7.3) Remove filter
8.Stashing
8.1) Stash download
REST API to manage MQTT service
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 (cancelling 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 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
List domain subscriptions
Service: POST /get-domain-subscriptions
Message: {âdomainNameâ : string, âtokenIdâ : tokenId}
Cookie: TokenId
This API needs administration rights (API user must have administrator rights at the destination HUB).
Allows to list all subscriptions that are currently installed and running for a given MyQttHUB (selected by domainName).
Service result:
Correct finalization: 200 OK [subscription, âŚ]
Failure: 400 Bad request
Administrative/domain subscribe
Service: POST /subscribe
Message: {âdomainNameâ : string, âsubscriptionsâ : List[[topic,qos]],
âclientIdâ : string, âstashToListâ : string, âtokenIdâ : tokenId}
Cookie: TokenId
This API needs administration rights (API user must have administrator rights at the destination HUB).
Allows to create a server side subscription at a given MyQttHUB (selected by domainName)
for a particular device (clientId).
subscriptions represent a list of subscriptions to install where each position includes
a list where index 0 includes topic filter and index 1 includes QoS to configured (0,1,2).
// subscriptions example declared in javascript
var subscriptions = [[ topic, qos], [topic2, qos2], [topic3, qos3]];
Service result:
Correct finalization: 200 OK
Failure: 400 Bad request
Administrative/domain unsubscribe
Service: POST /unsubscribe
Message: {âdomainNameâ : string, âsubscriptionsâ : List[topic],
âclientIdâ : string, âstashToListâ : string, âtokenIdâ : tokenId}
Cookie: TokenId
This API needs administration rights (API user must have administrator rights at the destination HUB).
Allows to remove a server side subscription at a given MyQttHUB (selected by domainName)
for a particular device (clientId).
subscriptions represent a list of subscriptions to unsubscribe.
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
List filters
Service: POST /filter/rules
Message: {âdomainNameâ : string, âtokenIdâ : tokenId}
Cookie: TokenId
Allows to list all filter rules that are currently installed in your HUB. domainName represents your unique domain hub name (like hub-username).
Service returns a list of filters, each one represents a json object.
Service result:
Correct finalization: 200 OK [filter, âŚ]
Failure: 400 Bad request
Add filter
Service: POST /filter/add
Message: {âdomainNameâ : string, âlabelâ : string, âprioâ : int,
âisActiveâ : boolean, âruleTypeâ : int, âpermissionâ : int,
âfilterItemsâ : string, âclientIdsâ : string,
âstashToListâ : string, âtokenIdâ : tokenId}
Cookie: TokenId
Allows to create a new filter into the destination MyQttHUB (selected by domainName). label and prio configures filter label and filter priority where high value represent low priority, low value high priority.
Filter rules with priority 0, 10 or 20, run before priority rules with 50,
60 and 70 priority.
permission is an integer that accepts the following values:
Permission value | Meaning | Description |
---|---|---|
1 | ok-allow | Accept/autorize action configured by this rule |
2 | deny-reject | Deny/reject action configured by this rule |
3 | dunno | Does not intercept or reject PUBLISH/SUBCRIBE operation but does apply optional operations like stashing |
ruleType is an integer that accepts the following values:
ruleType value | Meaning | Description |
---|---|---|
1 | limit-subscribe | Accept/rejects SUBCRIBE commands received according to permission and topic filters configured. |
2 | limit-publish | Accept/rejects PUBLISH commands received according to permission and topic filters configured. |
3 | content-control | Accept/rejects PUBLISH commands received according to permission and content filters configured. |
filterItems is configured, it includes a list of topic filters to be attached to the rule. This list of strings, separated by new line, is interpreted as a content filter list to match against PUBLISH payload to apply permission configured.
If filterItems is left empty, it matches all topics and payloads.
clientIds is an optional string list (new line separated) that includes clientIds that the rule applies to. In case clientIds is empty, rule applies to all clientIds.
stashToList is an optional string list (new line separated) that includes a list of stash names where this message will be stashed in case rule applies.
You can edit this filter rule by POSTing again with new values using same label.
Service result:
Correct finalization: 200 OK
Failure: 400 Bad request
Remove filter
Service: POST /filter/remove
Message: {âdomainNameâ : string, âlabelâ : string, âtokenIdâ : tokenId}
Cookie: TokenId
Allows to remove the filter selected by the provided label into the MyQttHUB selected by domainName.
Service result:
Correct finalization: 200 OK
Failure: 400 Bad request
Stash download
You can program your downloads using available REST HTTP API. There are two services:
- /calculate/stashed/download (service to get download size and quota consuption)
- /stashed/download (service that provides download support)
It is not required to use /calculate/stashed/download. You can directly use /stashed/download to get your stash content and consume quota associated.
Here is how to calculate your stash download (example built using curl; adapt it to your toolchain):
-
(Optional) Login and calculate your download stash:
curl -X POST https://node02.myqtthub.com/login -d â{âclientIdâ : âYourAdminClientIdâ, âuserNameâ : âYourUsernameâ, âpasswordâ : âaPasswordâ, âcleanSessionâ : false }â
{âclientIdâ:âmyQttTestDomainAdminâ,âvalidUntilâ:1549559337,âstampâ:1549386537,âcleanSessionâ:false,âtokenIdâ:âb0a7dda4-62e6-4e18-8008-0c780bd67f5eâ} -
As response, you get a tokenId for use in next interations:
{âclientIdâ:âYourAdminClientIdâ,âvalidUntilâ:1549559337,âstampâ:1549386537,âcleanSessionâ:false,âtokenIdâ:âb0a7dda4-62e6-4e18-8008-62e60bd67f5eâ}
-
Now calculate your download with:
curl --cookie âtokenId=b0a7dda4-62e6-4e18-8008-62e60bd67f5eâ -X POST https://node02.myqtthub.com/calculate/stashed/download -d â{âtokenIdâ : âb0a7dda4-62e6-4e18-8008-62e60bd67f5eâ, âdomainNameâ : âyour-hub-domainâ, âstashNameâ : âyour-stash-nameâ, âdownloadAsâ : âcsvâ, âdownloadFrameâ : âallâ}â
Service information:
API configuration API value Service name /calculate/stashed/download param: downloadName your hub domain param: stashName your stash name param: downloadFormat Download format. Allowed values are: csv, json, xml param: downloadFrame Configure/limits download period: allowed values (num)h for last (num) hours, (num)days, for last (num) days and âallâ to download all. Some valid examples are 24h, 7days, 31days or all -
Previous command will return an indication about download size and quota to be consumed:
{âsizeâ:12110,âqtaâ:3}
-
Now, you can download using:
curl --cookie âtokenId=e734b134-0f05-4405-935c-7a4834c0603câ -X POST https://node02.myqtthub.com/stashed/download -d â{âtokenIdâ : âe734b134-0f05-4405-935c-7a4834c0603câ, âdomainNameâ : âyour-hub-domainâ, âstashNameâ : âyour-stash-nameâ, âdownloadAsâ : âcsvâ, âdownloadFrameâ : âallâ}â
Service information:
API configuration API value Service name /stashed/download param: downloadName your hub domain param: stashName your stash name param: downloadFormat Download format. Allowed values are: csv, json, xml param: downloadFrame Configure/limits download period: allowed values (num)h for last (num) hours, (num)days, for last (num) days and âallâ to download all. Some valid examples are 24h, 7days, 31days or all -
As a response, given this example, you will get:
topic;qos;payload;retain;dup;clientId;userName;domainName;remoteAddr;stamp;date;operationId
sensors/temp;0;RmlyZSEhISEhIQ==;false;false;unknown-client-id;not-defined;your-hub-domain;not-defined;1545064449699;Mon Dec 17 17:34:09 CET 2018;D9793D5E1AB9092A8E45E1270D1B4975
sensors/temp;0;RmlyZSEhISEh;false;false;unknown-client-id;not-defined;your-hub-domain;not-defined;1545064393948;Mon Dec 17 17:33:13 CET 2018;9C7A930B1CF19C35556CBAE59448CAC6
message/test;0;RmlyZSEhISE=;false;false;unknown-client-id;not-defined;your-hub-domain;not-defined;1544807149647;Fri Dec 14 18:05:49 CET 2018;E1C0C230793678A78D35E5E66E0D606C
message/test;0;RmlyZSEhISEh;false;false;unknown-client-id;not-defined;your-hub-domain;not-defined;1544807061914;Fri Dec 14 18:04:21 CET 2018;B13243E2E7646E60A19312F05B24EC46