Back to top
Vastuu Group

Workflow using Insomnia Workspace

Last updated: March 16, 2021
|
Reading time: 12 min

Tags: V1 APIs, Insomnia REST API Workspace, Workflow

We aim to make onboarding process in Platform of Trust fast and easy for Developers without making them overwhelmed with complex structure and functionalities of core Platform APIs. Hence we represent a REST API workspace to get started.

This guide is for developers who are newly onboarding to Platform of Trust and wants to learn to play around with the core Platform components like identity network and data products. The purpose of this guide is to familiarize developers on how to use the Platform of Trust core APIs using a REST client space. For this, we will use Insomnia REST client.

The APIs that we will demonstrate here are Identity API , Product API , Application API and Broker API . In developer portal, you can check out profiles for Identity , Product , Application and Broker APIs

To follow the workflow demonstrated in this guide, you need to

  • understand key Platform terminologies like Data Product Application and Identities
  • have general knowledge on RESTful APIs
  • know how to use a REST client like Insomnia to make calls to APIs with proper authentications and needed query parameters

To get started, we will provide you a basic Insomnia workspace that contains related calls to Platform of Trust Application, Product, Identity, Access Control List (ACL), Broker and Context APIs.

Note: Keep in mind, that this Insomnia Workspace only supports V1 APIs from Platform of Trust. We will soon publish Postman Collection that would accommodate experimenting with the upcoming V2 APIs.

Register to Platform of Trust Sandbox

You can use the Sandbox to test Platform of Trust APIs, create identity networks and register and test data products in a secured and isolated manner.

Follow these instructions to register to Platform of Trust Sandbox

Start Using Sandbox!

Get Bearer Token

The Bearer token is a signed JWT token, in the format eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzY29w...DVs5aa, that is used to access and test Platform of Trust APIs in the Sandbox.

NOTE: Bearer token gets expired after 24 hours.

Follow these instructions to get your Bearer token.

To use in the Insomnia workspace, you need to exclude the "Bearer " part and copy the rest of the token.

NOTE: Make sure to remember getting the regenerated token after 24 hours to continue using it in the workspace.

Configure the Insomnia Workspace

To start using the workspace designed by Platform of Trust, you need to download and install Insomnia REST client in your workstation.

You also need to get the URL of the Insomnia workspace for Platform of Trust.

Get Platform of Trust Insomnia Workspace

Follow these instructions to set up the REST client and the workspace in your workstation. You may need to follow separate instructions depending on the operating system.

If you have followed all the above steps, you should now have the Insomnia REST client installed in your workstation.

You already should have imported the workspace via the URL, obtained and set your Bearer token from Platform of trust Sandbox.

You should also have selected Sandbox environment from the workspace.

Additional Plugins

You need two additional plugins to install in your Insomnia REST client, specifically to make calls to the Broker API:

1. Install this plugin from Platform of Trust to compute and add an X-Pot-Signature header to /broker/v1/fetch-data-product requests
2. Install this plugin to add custom timestamps.

Let's perform some actions in the Sandbox environment using the workspace!

Create a Group

A special type of identity that is required to create Data products or register Applications in Platform of Trust.

– 

Group

You can create a Group using the insomnia workspace in either of the following ways:

  1. Executing a chain request, or
  2. Creating an identity of type Group and connecting it to your own user identity

Executing a chain request to create a Group

Simply execute the POST One Click Create Group request in the workspace.

On Success, You will receive an HTTP 201 created response containing a Group named "DemoGroup". Make sure to save the @id of the group as it would be needed in future.

insomnia-chain-request-group.png

To verify the group creation, you can use MyWorld Standard App . After logging in, simply put the @id of the created Group in the search field. Under Graph view, you will see DemoGroup and your User Identity is connected together with a MemberOf type link.

myworld-user-to-group.png

You can read more about MyWorld Standard App from this use-case .

@id of the Group created via the chain request will be automatically set as the attribute value for "group_id" in the Sandbox environment for the workspace.

insomnia-one-click-group-id.png

NOTE: Learn about chain requests in Insomnia REST client here . In addition, you also need knowledge of Template Tags and Environment Variable .

Creating a Group identity and connecting it to your user Identity

Using Identity API, you can create a Group type identity and connect your own user identity to the group with a MemberOf type link.

From the workspace, expand the folder Identity Add Group. You will see two POST requests.

Create a Group

Simply execute this request to create a new group. You can change the value the name attribute for your group.

insomnia-create-group.png

On success, you will receive an HTTP 201 created response, that will contain the @id of the group. You should save this @id for future use.

From the response, you'll also see an attribute createdBy. This contains the identity @id of your user. You will need this in the next step.

Create MemberOf Link

In this request, you need to changes to some parts of the URL. For successful execution, your URL should be similar to the following:

pot_base_url/identities/V1/{YOUR_USER_IDENTITY_ID}/link/{GROUP_IDENTITY_ID}

Where the value of YOUR_USER_IDENTITY_ID = createdBy and GROUP_IDENTITY_ID = @id of the created Group in previous step.

NOTE: The value of pot_base_url comes from the Sandbox environment set in the workspace.

Insomnia-create-memberof-group.png

On success, you'll receive an HTTP 201 Created response with the @id of the MemberOf link from your user identity to the created group Group.

NOTE: To create a link between a User to a Group, the context in the request body always has to be https://standards.oftrust.net/v2/Context/Link/Role/MemberOf/. The link type should be MemberOf

NOTE: When manually creating Group, you need to put the @id of it in the "group_id" attribute under the Sandbox environment to further use in creating Data Product or Application.

insomnia-workspace-manual-groupid-setting.png

Creating an Identity Network

A digital representation of diverse concepts from the real world. e.g. a building, a person, a product, etc. Anything can be a separate identity in Platform of Trust

– 

Identity

A digital representation of a real-word set of entities, for example, a real-estate agency with living apartment houses under it.

– 

Identity Network

We recommend that before you start creating identities and linking them, draw a rough network that you want to create. This makes it easier to select the necessary identity types and their linked relationship.

Find out more details in our Identities and Link guide.

Below is the description of a demo Identity Network that you would be able to create using the related chain request in the insomnia workspace.

Demo Identity Network

Insomnia-Demo-Identity Network - Identity Network.jpg

The demo identity network represents the relationship between different elements associated with the Real Estate field. In this network, we have the following types of identities:

Building
Floor
Room
Temperature Sensor
CarbonDioxide Sensor

Data Products

Data Product itself is a special kind of identity.

To learn more about Identities and Context, check out our Ontology Viewer .

Defines both data content and the business elements of real-world entities in a machine-readable format. Data product defines how to query harmonized data from the relevant data source via the means of Platform of Trust Broker API.

– 

Data Product

You can use Product API to create Data Products in Platform of Trust. Read more about Data Products from our Data Product 101 guide.

Each identity is connected with another using a link.

A connection between two identities to establish a meaningful relationship between them.

– 

Link

Each link has a type indicating the relationship between two identities and a direction. In the demo identity network, the relationships are the following:

  1. Floor -- BelongsTo --> Building
  2. Room 1 -- BelongsTo --> Floor
  3. Room 2 -- BelongsTo --> Floor
  4. one Temperature Sensor -- BelongsTo --> Room 1
  5. one CarbonDioxide Sensor -- BelongsTo --> Room 1
  6. one Temperature Sensor -- BelongsTo --> Room 2
  7. one CarbonDioxide Sensor -- BelongsTo --> Room 2
  8. each Temperature Sensor -- AtDataProduct --> Temperature Data Product
  9. each CarbonDioxide Sensor -- AtDataProduct --> CarbonDioxide Data Product

To learn more about Identities and Context, check out our Ontology Viewer.

NOTE: A special link type is AtDataProduct. In an identity network, a sensor identity MUST be connected to a Data Product with a link type AtDataProduct. The direction MUST BE "from sensor to Data Product". This is important to consume harmonized data flow in an identity network.

IMPORTANT: You can always connect multiple sensors to one Data Product. You should remember that Temperature Sensor MUST BE connected to a Data Product for temperature, CarbonDioxide Sensor MUST BE connected to a Data Product for carbon-dioxide, and so on.

Insomnia chain request to create the demo identity network

Simply execute the POST One Click Create Demo Identity Network request in the workspace.

On Success, you should receive an HTTP 201 created response containing an Identity Network, which consists of the mentioned identities in the diagram.

insomnia-chain-create-identity-network.png

Again, you can check the created Identity Network in MyWorld App. Below is a picture of part of the Identity Network created:

oneclick-demo-identity-network.png

IMPORTANT: Using this instance of the workspace, you only would be able to create the demo Identity Network described above. In order to customize the request template to create an Identity Network of your choice, you need to learn about Chain Requests, Template Tag, and Environment variable in Insomnia.

Manual creation of an identity network using insomnia workspace

To manually create the demo Identity Network, you need to create specific Identities one at a time and establish a Link of a specific type between two identities.

Create an Identity

From Identity API folder, execute the call POST Create identity.

You need to specify the correct @context URL and @type of the identity to create. You can also specify some @data attributes for the identity.

On success, you will receive an HTTP 201 Created response containing @id of the created identity.

insomnia-create-identity.png

Save the @id of the identity created as it would be needed later to establish a link with other identities.

You can get @context URLs for Building , Floor , Room , Temperature Sensor , CarbonDioxide Sensor and Data Product from Ontology Viewer

Create a Link

In the Identity API folder, execute the request POST Create identity after adding the @ids of the from_identity and to_identity in the request URL

pot_base_url/identities/v1/:from_id/link/:to_id

On success, you will receive an HTTP 201 Created response containing information on the created link between two identities.

insomnia-link-identities.png

You need to specify the correct link direction via the request URL, @context URL for the link to create and @type of the link.

Read more about Link @contexts and @types in our Ontology Viewer .

NOTE: It is recommended that you create the 1st two identities, add between link them and continue creating identities and linking them until you create the entire identity network.

Manual creation of a data product using insomnia workspace

Using the workspace, you can create a Data Product by making a request to the Product API.

Under Product API folder, the POST request can be used to create a data product.

You need to include the following fields in the request body:

  • productCode: must be unique.
  • translatorUrl: URL of the server where your translator is hosted
  • URL under organizationPublicKey: public-key URL for the translator
  • type: you can use the value `RsaSignature2018` value here.

NOTE: A special link type is AtDataProduct. In an identity network, a sensor identity MUST be connected to a Data Product with a link type AtDataProduct. The direction MUST BE "from sensor to Data Product". This is important to consume harmonized data flow in an identity network.

On success, you'll receive an HTTP 201 Created response containing identityId, in addition to other entered field values for the created Data Product.

Remember to save the identityId for future use.

insomnia-create-dataproduct.png

NOTE: As discussed earlier, a Data Product identity MUST BE connected to a Sensor identity with a special link AtDataProduct. The direction MUST BE "from sensor to Data Product". Execute the POST Create Link request under Identity API folder with appropriate values in the request URL and body.

pot_base_url/identities/V1/{SENSOR_ID}/link/{DATA_PRODUCT_ID}
insomnia-link-product-sensor.png

Test Data Product

On the previous section, we created a demo identity network that contains one Temperature Data Product and one Carbon-Dioxide Data Product connected to relevant sensors. Now we'll show how you can test the Data Products to ensure harmonized data flow is generated.

Read our Consume Data Products guide for more details.

You need an Application to test a Data Product.

A third-party service or app that can request and receive harmonized data to utilize it for the intended purpose.

– 

Application

Read Register an Application guide to learn how you can use applications in the platform.

Insomnia chain request to test demo data products

At first, execute the POST One Click Test Demo DataProducts request.

On success, you'll receive a 200 OK response with the following body:

insomnia-one-click-dataproduct-test.png

Next, under Utility > Test Demo folder, open POST CO2 Data Product request.

You will find a request made to Platform of Trust Broker API to retrieve data from the CO2 sensors added in the identity network. The request body contains the following attributes:

  • timestamp: timestamp added to the Broker request in ISO-8601 format.
  • productCode: product code of the `Carbon-Dioxide Data Product`
  • parameters: set of parameters the translator can accept and process.
  • startTime and endTime: time-range for the returned result.

The Broker API returns a response containing harmonized sensor data about CO2 amount for both Rooms added in the identity network for the given time range.

insomnia-co2-data.png

A similar response can be found for the Temperature Data Product under Utility > Test Demo > POST Temperature Data Product request.

insomnia-temperature-data.png

Part of testing a Data Product involves creating an Application. This is done in the Utility > Test Demo > POST Create Application request. Here, Application API is used to create an application.

insomnia-create-application.png

On success, you will receive an HTTP 201 created response, that would also include clientSecrets and access_token generated for this Application. These values are needed to calculate x-pot-signature in order to call the Broker API for consuming data. You should save values for the clientSecrets and access_token.

NOTE: The additional Insomnia plugins mentioned in the third sections are needed to compute the x-pot-signature and put timestamps in the Broker API request.

A small note about Chain Requests

All chain requests demonstrated in this workspace consists of multiple API requests bundled together, where each request execute one specific action. Check out the subfolders under the Utility folder to access these individual requests. You can, for example, alter the single requests for creating the demo identity network to customize your own identity network structure. The individual requests for all one-click actions can be found under the Utility folder.

insomnia-workspace-utility.png

Again, you should have adequate knowledge on Chain Requests, Template Tag, and Environment variable in Insomnia.

Conclusion

Using this insomnia workspace, you would have now gained adequate knowledge about how Platform of Trust core APIs function. Also, you would be able to try out basic Sandbox features (e.g. creating Group, creating Identity network, testing a Data Product to consume harmonized data via an `Application`) in the Platform with one-click execution.

Ready to explore more?

Try Platform Sandbox

Improvement Suggestions? or a New Guide?

Tell us in GitHub