Hello World Tutorial (BurstChain®)¶

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

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

Initial Setup¶

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

The download can be found here: Insomnia 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.

insomnia picture

From here you can pick “New Request” or “New Folder”, for this we want to pick “New Request”.

This will cause a popup window where you can name your request and pick the type of request(GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD) from the dropdown menu.

insomnia picture

Once you are happy with these options you can hit create. This will make a new item in the panel on the left with the type of request and the name of your request, in this example it is called “My Request”.

You may also notice that the middle panel now has a place to select the type of request and a place to put a url along the top. Below that you will see tabs for “Body”, “Auth”, “Query”, “Header”, and “Doc”. We will make changes in those tabs below when we set up the request.

—¶

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 Body, this will open up a dropdown, you will want to select JSON. This will replace the word “Body” and 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"
        }]
    }
}

insomnia picture

Adding Authentication¶

The next step is to add the Authentication to the request. You will want to click on the tab that says “Auth” to switch to that panel and then click “Auth” again to open up a dropdown to pick the Authentication type which will be “Basic Auth”.

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

insomnia 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

So now Insomnia should look like this below:

insomnia picture

Sending the Request¶

To actually sent 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 on the right with a response. The Successful response should be:

{
  "message": "The operation was successful",
  "status": 200,
  "timestamp": {
    "$date": "2020-02-18T17:49:37.732Z"
  }
}

—¶

Setting up a Private and Public ID¶

Private ID¶

We can use the previous request in Insomnia and we will just need to make a couple modifications to it. First we want to duplicate the request in insomnia to do that move you mouse over “My Request” in the left panel and you’ll see a dropdown icon appear to the right of “My Request”. Click on that and you’ll see a dropdown, we want to pick “Duplicate”.

This will open a new Panel that will allow us to type in a Name for the new request. We can give the new request the name “Get Private ID”, then you can click create.

You will now see two requests on the left and the new request “Get Private ID” will be highlighted which means we have that request selected.

For getting a Private ID we will not want a body in the Request, click the body tab and open the dropdown and select “No Body”. The request type should be GET and we don’t need any Authorization.

To remove the Authorization Click on the tab to switch to that panel, then click it again to open the dropdown. From here select “No Authentication”, it should be at the bottom of the dropdown list.

When you have this set up correctly and you make the request you will see something similar to the Image below:

Private ID Image

Once you have the Private ID, make sure to memorize that or save it somewhere secure, this is how you access data you load onto the BurstIQ platform and how you maintain ownership of the data that is loaded, it will be linked to a Public ID.

Public ID¶

First we want to duplicate the Request we used for getting the Private ID, we can call this “Get Public ID”, if this is set up correctly with your Private ID you can make this call whenever you need to get your Public ID. To learn more about how the Public and Private ID’s are used you can read about it in the BurstChain® Documentation.

First we want to update the URL for this new Request, it should use this link:

URL: https://{ASSIGNED_SERVER}.burstiq.com/api/burstchain/id/public

This is similar to the previous request, the endpoint now ends with “public” instead of “private” and both requests are GET.

We also need to add a Header to the Request, “Click” on the “Header” tab and you will see a place to enter a “key” and a “value”

Header: Authorization

Value: ID <your-private-id>

Once you have done that the full request should look like the image, and the Request Response should have a Public ID in it.

public-id

—¶

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"
}

The actual Request body will contain an owner and optionally Asset Metadata in addition to the asset data:

  {
    "owners": ["<enter-your-public-id-here>"],
    "asset": {
        "id": "3456",
        "addr1": "123 Main St",
        "city": "Somewhere",
        "state": "XX",
        "zip": "12345"
    },
    "asset_metadata": {"extra": "value"}
  }

We need to create a new Request for adding an Asset, we can duplicate “Get Public ID” request similar to how we did above. You will need to update the Body to look like the image below and Because we set up the Authentication for the “Get Public ID” request already and we just duplicated that request we don’t have to for this request.

Note: If you created a new request instead of duplicating the request we already set up you will need to select the “Header” tab and add the Authorication header with the Value ID <your-private-id>

We will want to change the JSON Body of the request to now look like the image below using the JSON Asset above. Make sure to add in your Public ID.

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/burstchain/<client-name>/<collection-name>/asset

You will want to substitute <collection_name> with “address” because that is the collection we are adding the asset too. We will also need to substitute <client-name> with your uses client name.

Insomnia should look like the image below, if you hit “Send” you should see a success response in the response panel on the right. You will also be returned an asset_id, this can be used to lookup the asset you inserted into the collection, but that isn’t the only way because you can also use one of the query languages which is covered in the sections below.

insomnia picture

—¶

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

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/burstchain/{client}/{collection_name}/assets/query where {collection_name} is the value address, the Request type is POST, and the JSON body is set as:

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

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

insomnia 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/burstchain/{client}/{collection_name}/assets/query where {collection_name} is the value address, the Request type is POST, and the JSON body is set as:

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

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

insomnia picture

Using TQLFlow¶

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

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

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

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

A lot of information comes back for these queries because there is alot that goes with storing the asset on a BurstChain®, the information we put in the chain is under asset. To learn more about what the other information is please read the Intro to BurstChain®

{
  "message": "The operation was successful",
  "status": 200,
  "timestamp": {
    "$date": "2020-02-18T20:56:56.049Z"
  },
  "assets": [
    {
      "hash": "<hash-value>",
      "timestamp": {
        "$date": "2020-02-18T20:27:07.118Z"
      },
      "type": "asset",
      "operation": "create",
      "owners": [
        "<owners-public-id>"
      ],
      "signer": "<signer-value>>",
      "signature": "<signature-value>",
      "dictionary": "address",
      "asset": {
        "id": "3456",
        "addr1": "123 Main St",
        "city": "Somewhere",
        "state": "XX",
        "zip": "12345"
      },
      "digest_alg": "<alg-value>",
      "previous_hash": "<previous-has-value>",
      "asset_id": "<asset-id-value>",
      "asset_metadata": {
        "extra": "value"
      }
    }
  ]
}

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¶

TBD