REST API to manage MyQttHub service

#1

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:

  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 (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):

  1. (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”}

  2. 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”}

  3. 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

  4. Previous command will return an indication about download size and quota to be consumed:

    {“size”:12110,“qta”:3}

  5. 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

  6. 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

Downloading a Stash using JSON, CSV (Excel) or XML format with MyQttHub
MyQttHub ES -- Empieza por aquĂ­
Descargando un Stash usando JSON, CSV (Excel) o formato XML con MyQttHub
MyQttHub EN -- Start here
Problemas con conexion API usando Bubble.io
Sending messages to specific MQTT devices
Is it possible to access /devices/connected from a device which is not the domain admin?
MyQttHub y la especificaciĂłn SparkPlug
Connecting to MyQttHub through AT Commands
Question: How to establish connection on iphone's IoT OnOff
How to unsubscribe all topics
Sending messages to specific MQTT devices
MyQttHub and SparkPlug Spec
Can't connect - New account
Recibir los valores de los topicos