REST API to manage MyQttHub service (ReactiveMyQtt v6.7.773)


#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 (canceling 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

6.Publishing and getting messages

6.1) Publish message for a current logged device
6.2) Pull messages for a current logged device

7.Stashing

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

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


Descargando un Stash usando JSON, CSV (Excel) o formato XML con MyQttHub
Downloading a Stash using JSON, CSV (Excel) or XML format with MyQttHub