Skip to content

Hello World Tutorial (IQ)

If you haven’t yet please read the IQ Introduction before going through with this tutorial.

Postman is one way to test out and work with the API, This Tutorial will walk through downloading and setting up Postman. This Tutorial covers the same steps as the other two “Hello World” Tutorials which use cURL commands or Insomnia.

Starting

BurstIQ Administrators must create a new client data-space before any interactions can begin. Once that and a username/password credential has been created with an ADMIN role it is possible to start the tutorial. Remember that a “client” name identifies a unique data-space within the Secure Data Grid that segments that client’s data from others.

The below steps are all done using Postman, the main differences between the commands below are the URL, the Authorization, the Request Body, and the Request Type.

Initial Setup

First you will need to Download and Install the Postman App from their website.

The download can be found here: Postman Download

Once it is installed you will see a screen like this

To make a new Request you will want to Click the “plus” button you see circled in the image below.

postman picture

From here the window below will open up to allow you to set up your request.

If you click on GET This will cause a popup window where you can pick the request type(GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD) from the dropdown menu. and immediately next to the Request type you can put the API Url (We go over that below).

To keep these requests you can save them by clicking the Save button in the top right and you should have the option to name the request, give it a description and start a collection of requests.

For Postman you will need to make a Collection to save the request, the Collection is a way to group requests together, create a collection named “Hello World” for the tutorial and name the request something like “My Request”.

postman picture

Creating a Dictionary

Setting up the Request Body

You will need to set up the dictionary and load that using the API. We will define the dictionary in the body of the request. To do that you can click on the Body tab, this will open up an empty window for adding your body and will have a couple different body types to pick from. You can select “raw” and the type of raw input defaults to “Text” you can change that by clicking that and opening the dropdown menu. For our request we want the type of be JSON. You can then add in the dictionary information like you see below in the image.

Dictionary in JSON format:

{
    "collection": "address",

    "indexes": [{
        "unique": true,
        "attributes": ["id"]
    }],

    "rootnode": {
        "attributes": [{
            "name": "id",
            "required": true
        }, {
            "name": "addr1"
        }, {
            "name": "addr2"
        }, {
            "name": "city"
        }, {
            "name": "state"
        }, {
            "name": "zip"
        }]
    }
}

postman picture

Adding Authentication

The next step is to add the Authentication to the request. You will want to click on the tab that says “Authentication” to switch to that panel and then open up the dropdown for “Type” and select “Basic Auth”.

Now you can enter in your Username and Password as you can see in the image.

postman picture

Adding the URL

Now we want to Add in the URL and make sure the correct type of request is being made.

The base URL for this request is https://{ASSIGNED_SERVER}.burstiq.com

The API Path you are going to use for creating a dictionary is: /api/metadata/dictionary

The type of call should be PUT

Postman should look like the image below:

Insert Picture of Postman with Everything filled out postman picture

Sending the Request

To actually send the request you can hit “Send” which is located to the right of where you typed in the URL.

If things were successful you will see a response in the panel along the bottom.

Adding an Asset

Once you have the dictionary defined you can then add Assets to the collection that you can eventually query. We are going to insert the Asset below into our newly defined dictionary “address”.

{
    "id": "3456",
    "addr1": "123 Main St",
    "city": "Somewhere",
    "state": "XX",
    "zip": "12345"
}

We can use the previous request in Postman and we will just need to make a couple modifications to it. First we want to duplicate the request in Postman to do that move you mouse over the tab for the request we are duplicating, Right click and you’ll see the option to “Duplicate Tab”.

postman picture

This will open a new Tab for the new request. If you hit the “down arrow” in the “Save” button for this new tab you can select “Save as” and rename this request. We are adding an Asset for this request so a name like “Adding Asset” could be helpful to differentiate from other request.

You will now see two request tabs and the new request “Add Asset” will be highlighted which means we have that request tab open.

We will want to change the JSON Body of the request to now look like the image below using the JSON Asset above.

postman picture

The Authentication tab can stay the same because it already has the Username and Password you entered in for the previous request since we Duplicated the request.

Note: If you created a new request instead of duplicating the request we already set up you will need to select Basic Auth and add your username and password to the “Auth” tab

Now we just need to update the URL and make sure we have the correct request type. The new Url will have the same base but the API path will be different.

URL: https://{ASSIGNED_SERVER}.burstiq.com/api/iq/{collection_name}

You will want to substitute {collection_name} with “address” because that is the collection we are adding the asset too.

Postman should have a successful response in the bottom panel once you have “Sent” for the request.

Querying the Asset

Now that we have created our dictionary and added an asset we will want to be able to query that data we added.

We can query for the asset a few different ways, an example request for each way is shown below.

TQL WHERE Clause, TQL, and TQLFlow all use the same API Endpoint path but accept different attributes in the JSON Request Body. Map Reduce uses a different API Endpoint path and a different JSON Request Body.

Note: For Ease of creating a Request using Postman you can use the same method shown in “Adding An Asset”, where you just Duplicate a current request. This will bring over all of the current configurations from that request and you will only need to update the JSON Body, the URL path and the Request Type.

If you are using an IQ endpoint (which is what we use in this tutorial) Basic Authentication is needed. If you are using a BurstChain® Endpoint a private ID is needed which is covered in the BurstChain® Hello World Tutorials.


Using TQL WHERE Clause

Your new request should look like this if you are querying using TQL WHERE Clause. See how the URL now ends in /api/iq/{collection_name}/query where {collection_name} is the value address, the Request type is POST, and the JSON body is set as:

{
  "tqlWhereClause": "WHERE state = 'XX'"
}

Note: For further information on how to Structure a where clause see the Query Languages Section on TQL WHERE Clause Query

postman picture


Using TQL

Your new request should look like this if you are querying using TQL query. See how the URL now ends in /api/iq/{collection_name}/query where {collection_name} is the value address, the Request type is POST, and the JSON body is set as:

{
  "queryTql": "SELECT * FROM address WHERE state = 'XX'"
}

Note: For further information on how to Structure a TQL query statement see the Query Languages Section on Basic TQL

postman picture


Using TQLFlow

Your new request should look like this if you are querying using TQLFlow. See how the URL now ends in /api/iq/{collection_name}/query where {collection_name} is the value address, the Request type is POST, and the JSON body is set as:

{
  "queryTqlFlow": "WHERE state = 'XX'"
}

Note: For further information on how to Structure TQLFlow see the Query Languages Section on TQLFlow

postman picture


Result

Notice how regardless of the type of query you use from above it is possible to get the same response for all 3 types of queries in this example because the query statements above are fairly simple and they all support the needed WHERE Clause to get this response:

{
  "message": "The operation was successful",
  "status": 200,
  "timestamp": {
    "$date": "2020-02-19T17:43:25.971Z"
  },
  "records": [
    {
      "id": "3456",
      "addr1": "123 Main St",
      "city": "Somewhere",
      "state": "XX",
      "zip": "12345"
    }
  ]
}

Note: Each of these types of queries have their own use cases and more information can be found in the section Query Languages where each type of query has its own in depth section.

More Information on each:

TQL WHERE Clause

Basic TQL

TQLFlow

Deleting an Asset