Tools and Software

Postman

Postman (freeware) allows you to test the APIs to implement the services. If you do not feel comfortable with this tool, you can use an alternative solution for API testing. If you want to go ahead with Postman

1. Download the software from the website and install it

2. Download the swagger file from the REST API web page

3. Upload the swagger file in Postman:

   • click the 'Import' button near the name of your workspace and upload the swagger file. 

   • select the 'Documentation' item from the dropdown menù 'Link this collection as'.

   • If you do not have yet a workspace, create a new one using the Workspace menu.

4. By uploading the swagger file it is automatically created a collection that contains all the Security Services REST APIs organized with the same structure of the documentation . Moreover:

   •  the "baseUrl" that is the url of the API Interface  of the u-blox Thingstream delivery platform will be automatically set to https://ssapi.services.u-blox.com/v1/

5. If not yet done, generate the access key and the secret from Thingstream service delivery portal, in  Security Service section. Remember to download and save Access key and Secret in a secure place because the Secret is no longer accessible in the portal after the generation.

6. Test the connection with u-blox Thingstream server with the authentication API: 

   •  Select /authenticate API in the collection just created

   • configure the access Key and the Secret in the 'Body parameters' section of the API

   • Send the API and verify that in the 'Body' section you obtain the  AuthToken and RefreshToken and that Status code is 200 (OK)

Remember that the AuthToken is valid for 1 hour. For more information, refer to the online documentation.

Using the APIs

Once the AuthToken has been generated, you can use all the other APIs. Here below an example on how to configure the parameters for /deviceprofile/get: 

1. Create the device profile

   • Create a device profile in the Thingstream portal on 'Security services > Device Profile' section

   • As output you will have a 'Device profile name' (the one provided by you in the wizard) and a 'Device profile Uid' that is an alphanumeric string.

2. In Postman, select the /deviceprofile/get API. 

   • In the 'Authorization' section, select 'Bearer Token' from the Type dropdown menu. You can also set the AuthToken for all the APIs by selecting the entire API collection 'Security Services REST API' at the root of the API list. In this case the AuthToken will used for all the APIs 

   • Copy the 'AuthToken' without double quotes in the Token field on the right side. Be careful in pasting only the alpahnumeric string between the double quotes. Remove the double quotes and any other character like the carriage return or the new line at the end of the token (if present).

   • In the 'Body' section, replace the text with the one below

{

    "ProfileName": "TestPostman",

    "PageNumber": 1

}

'TestPostman' is the Device profile name created for this example. Replace it with the name of the device profile just created.  All the parameters are case sensitive. 'Page number' is a number (not a string) without double quotes and it is an optional parameter.

2. • Send the API by clicking the blue button. Verify that the result code is 200 (OK) and check the output at the bottom of the page. 

As an additional test you can:

• add a tag to the device profile from the Thingstream portal accessing to the 'Device Profiles' section, then select the desired Device profile and add a tag using the proper button.

• send the API specifying the tag in the body section instead of the Device profile name:

{

    "TagNames": [

        "testtag1"

    ]

}

Replace 'testtag1' with the name of the tag just created by you.

• Verify that the result code is 200 (OK) and check the output at the bottom of the page.