Back to top
Vastuu Group

Identity and Data Discovery

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

Tags: V1 APIs, Identity, Link, Identity Network, Discovery, Data Product

This guide is for developers who have registered to Platform of Trust and gained moderate knowledge on basic Platform features and technologies, specifically about Identity, Link and Identity Network. In this guide, we will talk about how to utilize Identity API and discover identities in an identity network, as well as discovering Data products. Get more information about Identity API from its profile in Developer Portal.

NOTE: We recommend reading Identities and Links guide before proceeding further. It is important to know how you can create an Identity Network before trying out the discovery functionality of Identity API.

A complex identity network can hold a large number of Identities of different types that are connected to each other with multiple Links. Together they form a complex structure to represent information around us. Even though all this data is organized and smaller components are related one to another, it can be hard to navigate and find certain Identities and Links. For this purpose Platform of Trust provides Discovery functionality to users.

To follow this guide, it is important that:

  • You take a look at our Ontology Viewer to get some ideas about context, JSON schema, etc. associated with every identity.
  • You have general knowledge of RESTful APIs.
  • You have a bearer token to access Platform of Trust APIs in the Sandbox environment
  • You have knowledge about Identities and links and know how to create an Indeitty Network with Platform of Trust Identity API

Note: Keep in mind, that version 1 APIs from Platform of Trust has been used to demonstrate this.

Identity API and discovery feature

The Discovery feature is a part of Identity API. It will be useful for users who need to traverse the identity network to find identities of a certain context, connected to each other in a certain way. Practically users should be able to run API requests to fetch Identities of certain Context in the network that also linked to each other in the same way. E.g. all TemperatureSensor identities that BelongsTo Building identity.

[In this case, users might want to know how many sensors of a certain type they have in their network. For such problems Identity API and its discovery functionality come in handy.]

NOTE: Discovery functionality is a part of the Identity API. Not a separate API.

Identity Network and discovery feature

complex-network.jpg

However, it is already not an easy task to pinpoint the exact relationships between all identities. Especially this is hard if it would be logically correct to connect e.g. 1 Room to multiple Apartment, for some other use cases such scenario can be the reality.

In this case, it is useful to have a possibility to be able to tell e.g.

  • How many different sensors connected to Housing Company 1?
  • How many sound sensors connected to Apartment 3?
  • Is there any Data products connected to any of Temperature sensors, with which Housing company 2 is connected?

In order to be able to easily answer such questions, users can send a discovery request to the Identity API.

For demonstration purposes let's create a fraction of a similar, but not exactly the same identity network on the picture above. We can have one Housing company connected to a Building connected to an Apartment connected to 2 Room identities connected to 6 Sensor identities. In order to learn how to create new identities and link them together, you should follow Identities and Links guide .

NOTE: You should save all output from each request while creating identities to save time in the following steps of this guide.

Here's the image of identity network that you have in the end:

small-network.jpg

myworld-identity.png

myworld-identity-list.jpg

In total there are around 11 identities and 10 links besides your own user identity.

Identities discovery

In order to discover identities using Identity API, you must understand certain basic principles of discovery feature. First of all, discovery works best if you are already familiar with the structure of the network you want to explore. Secondly, the use of the discovery feature requires having a properly defined identity network. If any link or identity has an incorrect context or link direction, it most likely prevents users from reaching correct results while using this feature.

NOTE: The Discovery feature is not a search feature. It works best for users who are already at least a little bit familiar with the identity network.

Let's try to look up for identities connected to the Building identity of the network you might have created in previous steps. Keep in mind that in actual e.g. working environment, usually available identity network is dramatically more complex and can contain a large number of identities and links. E.g. real estate agents might want to ask How many rooms in all apartments of a certain type are belong to this building?. In a real-world scenario, it will be impossible to answer this question just by looking at some schemes. Therefore we must use the discovery feature of Identity API to answer such a question. Let's send a request to Identity API to find out how many Room identities connected to the Building.

Sending valid discovery requests requires multiple parameters to be specified such as @id of identity starting point, @type and direction of links and type of identities to be iterated, how deep Identity API will try to look up, etc.

NOTE: There are only 4 required query parameters: fromId, linkContext, identityContext and linkDirection.

First of all, we need to know fromId. This value specifies @ID of identity where we want the discovery feature to start iterating identities in a network. This value is different for different users and networks. If you haven't saved output or ID while creating identities and you are not using GUI tool , then you can use the discovery feature to fetch Building identity connected to your own personal identity via BelongsTo link. See Login API to get ID of your own identity.

NOTE: List of useful contexts as URLs:

  • https://standards.oftrust.net/v2/Context/Link/BelongsTo/
  • https://standards.oftrust.net/v2/Context/Identity/Equipment/Device/Sensor/
  • https://standards.oftrust.net/v2/Context/Identity/Structure/Building/
  • https://standards.oftrust.net/v2/Context/Identity/Space/Room/
  • https://standards.oftrust.net/v2/Context/Identity/Product/DataProduct/

Send "GET" request to https://api-sandbox.oftrust.net/identities/v1/discovery with updated fromId and other query parameters:

fromId: {ID of your own personal identity}
linkDirection: "IN"
linkContext: "https://standards.oftrust.net/v2/Context/Link/BelongsTo/"
identityContext: "https://standards.oftrust.net/v2/Context/Identity/Structure/Building/"

Request: GET /identities/v1/discovery

curl --request GET \
  --  --url 'https://api-sandbox.oftrust.net/identities/v1/discovery?linkContext=https%3A%2F%2Fstandards.oftrust.net%2Fv2%2FContext%2FLink%2FBelongsTo%2F&fromId=ec1dcb7c-55ba-4af6-8359-4a75b01e0178&identityContext=https%3A%2F%2Fstandards.lifeengine.io%2Fv1%2FContext%2FIdentity%2FThing%2FHumanWorld%2FSystem%2FBuiltEnvironment%2FBuilding%2F&linkDirection=IN' \
  --header 'authorization: Bearer eyJ0eXAiOiJKV1QiLCJ...ah20'

Response: Ok
Status: 200 OK
Body:

{
  "identities": {
    "170bb798-0f91-498d-8fa5-7b690cd1a1ca": {
      "@context": "https://standards.oftrust.net/v2/Context/Identity/Structure/Building/",
      "@type": "Building",
      "@id": "170bb798-0f91-498d-8fa5-7b690cd1a1ca",
      "data": {
        "name": "Building 1"
      },
      "metadata": {
        "createdAt": "2020-04-21T17:45:18+00:00",
        "createdBy": "ec1dcb7c-55ba-4af6-8359-4a75b01e0178",
        "updatedAt": "2020-04-21T17:45:18+00:00",
        "updatedBy": "ec1dcb7c-55ba-4af6-8359-4a75b01e0178"
      }
    }
  },
  "pagination": {
    "links": [
      {
        "rel": "first",
        "href": "https://api-sandbox.oftrust.net/identities/v1/discovery?offset=0&limit=20&linkContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FLink%2FBelongsTo%2F&fromId=ec1dcb7c-55ba-4af6-8359-4a75b01e0178&identityContext=https%3A%2F%2Fstandards.lifeengine.io%2Fv1%2FContext%2FIdentity%2FThing%2FHumanWorld%2FSystem%2FBuiltEnvironment%2FBuilding%2F&linkDirection=IN"
      },
      {
        "rel": "self",
        "href": "https://api-sandbox.oftrust.net/identities/v1/discovery?linkContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FLink%2FBelongsTo%2F&fromId=ec1dcb7c-55ba-4af6-8359-4a75b01e0178&identityContext=https%3A%2F%2Fstandards.lifeengine.io%2Fv1%2FContext%2FIdentity%2FThing%2FHumanWorld%2FSystem%2FBuiltEnvironment%2FBuilding%2F&linkDirection=IN"
      },
      {
        "rel": "last",
        "href": "https://api-sandbox.oftrust.net/identities/v1/discovery?offset=0&limit=20&linkContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FLink%2FBelongsTo%2F&fromId=ec1dcb7c-55ba-4af6-8359-4a75b01e0178&identityContext=https%3A%2F%2Fstandards.lifeengine.io%2Fv1%2FContext%2FIdentity%2FThing%2FHumanWorld%2FSystem%2FBuiltEnvironment%2FBuilding%2F&linkDirection=IN"
      }
    ],
    "hasMore": false,
    "totalCount": 1
  }
}

From this response you should get ID from @id field for Building identity in your network. This is actually how discovery identity works in general, but how about the use case we specified before? Let's continue with finding Room identities connected to Building.

We just received a value for fromId parameter. Since we want to find how many Room identities are linked to Building, then we know another query parameter identityContext - https://standards.oftrust.net/v2/Context/Identity/Space/Room/. You can find more available context values at Platform of Trust ontology repository. Thirdly we need to specify how those identities relate to each other, if you followed the exact structure on the image in the previous step, then all identities should be linked to each other with BelongsTo type of link. Just like identityContext, you need to specify linkContext by providing url as a value https://standards.oftrust.net/v2/Context/Link/BelongsTo/.

Let's send another "GET" request to https://api-sandbox.oftrust.net/identities/v1/discovery with query parameters:

fromId: {ID of Building identity}
linkDirection: "IN"
linkContext: "https://standards.oftrust.net/v2/Context/Link/BelongsTo/"
identityContext: "https://standards.oftrust.net/v2/Context/Identity/Space/Room/"

Request: GET /identities/v1/discovery

curl --request GET \
  --url 'https://api-sandbox.oftrust.net/identities/v1/discovery?linkContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FLink%2FBelongsTo%2F&fromId=170bb798-0f91-498d-8fa5-7b690cd1a1ca&identityContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FIdentity%2FRoom%2F&linkDirection=IN&=' \
  --header 'authorization: Bearer eyJ0eviNT7xla...tasVICNCOqbCMZ7TXpAlutg'

Response: Ok
Status: 200 OK
Body:

{
  "identities": {
    "a9fd6bf6-bf53-4a42-9704-baae81a7e227": {
      "@context": "https://standards.oftrust.net/v2/Context/Identity/Space/Room/",
      "@type": "Room",
      "@id": "a9fd6bf6-bf53-4a42-9704-baae81a7e227",
      "data": {
        "name": "Sunny room"
      },
      "metadata": {
        "createdAt": "2020-04-21T17:46:26+00:00",
        "createdBy": "ec1dcb7c-55ba-4af6-8359-4a75b01e0178",
        "updatedAt": "2020-04-21T17:46:26+00:00",
        "updatedBy": "ec1dcb7c-55ba-4af6-8359-4a75b01e0178"
      }
    },
    "df845352-a00b-47f5-bf35-eafa85f25f55": {
      "@context": "https://standards.oftrust.net/v2/Context/Identity/Space/Room/",
      "@type": "Room",
      "@id": "df845352-a00b-47f5-bf35-eafa85f25f55",
      "data": {
        "name": "Rainy room"
      },
      "metadata": {
        "createdAt": "2020-04-21T17:52:12+00:00",
        "createdBy": "ec1dcb7c-55ba-4af6-8359-4a75b01e0178",
        "updatedAt": "2020-04-21T17:52:12+00:00",
        "updatedBy": "ec1dcb7c-55ba-4af6-8359-4a75b01e0178"
      }
    }
  },
  "pagination": {
    "links": [
      {
        "rel": "first",
        "href": "https://api-sandbox.oftrust.net/identities/v1/discovery?offset=0&limit=20&linkContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FLink%2FBelongsTo%2F&fromId=170bb798-0f91-498d-8fa5-7b690cd1a1ca&identityContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FIdentity%2FRoom%2F&linkDirection=IN"
      },
      {
        "rel": "self",
        "href": "https://api-sandbox.oftrust.net/identities/v1/discovery?linkContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FLink%2FBelongsTo%2F&fromId=170bb798-0f91-498d-8fa5-7b690cd1a1ca&identityContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FIdentity%2FRoom%2F&linkDirection=IN"
      },
      {
        "rel": "last",
        "href": "https://api-sandbox.oftrust.net/identities/v1/discovery?offset=0&limit=20&linkContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FLink%2FBelongsTo%2F&fromId=170bb798-0f91-498d-8fa5-7b690cd1a1ca&identityContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FIdentity%2FRoom%2F&linkDirection=IN"
      }
    ],
    "hasMore": false,
    "totalCount": 2
  }
}

Read more about GET /identities/v1/discovery request in Identity API

As you can see Identity API returns 2 Room identities linked to Building identity. And this will be the answer to real estate agent that asked before How many rooms in all apartments of certain type belong to this building?.

Let's do similar query, but this time let's figure out how many Carbon Dioxide Sensor identities are in the network. According to the scheme there should be 2. But in order to perform such query successfully starting with Building identity as a starting point we need to add additional parameter into the query.

Discovery depth

Let's replace value of identityContext with https://standards.oftrust.net/v2/Context/Identity/Equipment/Device/Sensor/CarbonDioxideSensor/ in our last query.

Request: GET /identities/v1/discovery

curl --request GET \
  --url 'https://api-sandbox.oftrust.net/identities/v1/discovery?linkContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FLink%2FBelongsTo%2F&fromId=170bb798-0f91-498d-8fa5-7b690cd1a1ca&identityContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FIdentity%2FDevice%2FSensor%2FCarbonDioxideSensor%2F&linkDirection=IN&=' \
  --header 'authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOi...qgLW0LWP9rmenc'

Response: Ok
Status: 200 OK
Body:

{
  "identities": {},
  "pagination": {
    "links": [
      {
        "rel": "first",
        "href": "https://api-sandbox.oftrust.net/identities/v1/discovery?offset=0&limit=20&linkContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FLink%2FBelongsTo%2F&fromId=170bb798-0f91-498d-8fa5-7b690cd1a1ca&identityContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FIdentity%2FDevice%2FSensor%2FCarbonDioxideSensor%2F&linkDirection=IN"
      },
      {
        "rel": "self",
        "href": "https://api-sandbox.oftrust.net/identities/v1/discovery?linkContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FLink%2FBelongsTo%2F&fromId=170bb798-0f91-498d-8fa5-7b690cd1a1ca&identityContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FIdentity%2FDevice%2FSensor%2FCarbonDioxideSensor%2F&linkDirection=IN"
      },
      {
        "rel": "last",
        "href": "https://api-sandbox.oftrust.net/identities/v1/discovery?offset=0&limit=20&linkContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FLink%2FBelongsTo%2F&fromId=170bb798-0f91-498d-8fa5-7b690cd1a1ca&identityContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FIdentity%2FDevice%2FSensor%2FCarbonDioxideSensor%2F&linkDirection=IN"
      }
    ],
    "hasMore": false,
    "totalCount": 0
  }
}

Well, Identity API does not return any identities according to our parameters. In order to make the query to discover across more identities in the network on scheme, we need to add one more additional parameter to the query - maxDepth. maxDepth is an optional query parameter, which has value of 2 by default. This parameter defines how many hops Identity API will make starting from identity specified in fromId parameter.

NOTE: The hop count refers to the number of intermediate network identities between source and destination.

Let's try the last query with maxDepth set to 3.

Request: GET /identities/v1/discovery

curl --request GET \
  --url 'https://api-sandbox.oftrust.net/identities/v1/discovery?linkContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FLink%2FBelongsTo%2F&fromId=170bb798-0f91-498d-8fa5-7b690cd1a1ca&identityContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FIdentity%2FDevice%2FSensor%2FCarbonDioxideSensor%2F&linkDirection=IN&maxDepth=3&=' \
  --header 'authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...bbECqgLW0LWP9rmenc'

Response: Ok
Status: 200 OK
Body:

{
  "identities": {
    "d6cf3b59-3f03-40e2-bb52-821df2341b9f": {
      "@context": "https://standards.oftrust.net/v2/Context/Identity/Equipment/Device/Sensor/CarbonDioxideSensor/",
      "@type": "CarbonDioxideSensor",
      "@id": "d6cf3b59-3f03-40e2-bb52-821df2341b9f",
      "data": {
        "name": "CO2 1"
      },
      "metadata": {
        "createdAt": "2020-04-21T17:49:38+00:00",
        "createdBy": "ec1dcb7c-55ba-4af6-8359-4a75b01e0178",
        "updatedAt": "2020-04-21T17:49:38+00:00",
        "updatedBy": "ec1dcb7c-55ba-4af6-8359-4a75b01e0178"
      }
    },
    "d6f39184-f457-4818-90ee-ead5664dfa08": {
      "@context": "https://standards.oftrust.net/v2/Context/Identity/Equipment/Device/Sensor/CarbonDioxideSensor/",
      "@type": "CarbonDioxideSensor",
      "@id": "d6f39184-f457-4818-90ee-ead5664dfa08",
      "data": {
        "name": "CO2 2"
      },
      "metadata": {
        "createdAt": "2020-04-21T17:53:03+00:00",
        "createdBy": "ec1dcb7c-55ba-4af6-8359-4a75b01e0178",
        "updatedAt": "2020-04-21T17:53:03+00:00",
        "updatedBy": "ec1dcb7c-55ba-4af6-8359-4a75b01e0178"
      }
    }
  },
  "pagination": {
    "links": [
      {
        "rel": "first",
        "href": "https://api-sandbox.oftrust.net/identities/v1/discovery?offset=0&limit=20&linkContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FLink%2FBelongsTo%2F&fromId=170bb798-0f91-498d-8fa5-7b690cd1a1ca&identityContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FIdentity%2FDevice%2FSensor%2FCarbonDioxideSensor%2F&linkDirection=IN&maxDepth=3"
      },
      {
        "rel": "self",
        "href": "https://api-sandbox.oftrust.net/identities/v1/discovery?linkContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FLink%2FBelongsTo%2F&fromId=170bb798-0f91-498d-8fa5-7b690cd1a1ca&identityContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FIdentity%2FDevice%2FSensor%2FCarbonDioxideSensor%2F&linkDirection=IN&maxDepth=3"
      },
      {
        "rel": "last",
        "href": "https://api-sandbox.oftrust.net/identities/v1/discovery?offset=0&limit=20&linkContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FLink%2FBelongsTo%2F&fromId=170bb798-0f91-498d-8fa5-7b690cd1a1ca&identityContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FIdentity%2FDevice%2FSensor%2FCarbonDioxideSensor%2F&linkDirection=IN&maxDepth=3"
      }
    ],
    "hasMore": false,
    "totalCount": 2
  }
}

Now, "totalCount": 2 is exactly the result we expected. You will achieve the same result if you set maxDepth to 4 or 5, because all identities from previous hops will be included as well.

NOTE: maxDepth parameter must be from 1 to 5.

Benefits of nested context path

Sometimes you don't want to look up for particular Sensor type, but rather for all Sensor identities. In the network we have created we should have in total 6 Sensor identities of 3 types:

Temperature Sensor, Carbon Dioxide Sensor and Humidity Sensor.

Their context URLs are:

Due to the fact that all URLs are sub-path of https://standards.oftrust.net/v2/Context/Identity/Equipment/Device/Sensor/ URL, here we can use the main path of context URL to specify all sensors in the query using: https://standards.oftrust.net/v2/Context/Identity/Equipment/Device/Sensor/ as a value for identityContext.

Request: GET /identities/v1/discovery

curl --request GET \
  --url 'https://api-sandbox.oftrust.net/identities/v1/discovery?linkContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FLink%2FBelongsTo%2F&fromId=170bb798-0f91-498d-8fa5-7b690cd1a1ca&identityContext=https%3A%2F%2Fstandards.oftrust.net%2Fv2%2FContext%2FIdentity%2FEquipment%2FDevice%2FSensor%2F&linkDirection=IN&maxDepth=5&=' \
  --header 'authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...LWP9rmenc'

Response: Ok
Status: 200 OK
Body:

{
  "identities": {
    "21e69036-03d1-4f73-97b2-f7114af589f4": {
      "@context": "https://standards.oftrust.net/v2/Context/Identity/Equipment/Device/Sensor/TemperatureSensor/",
      "@type": "TemperatureSensor",
      "@id": "21e69036-03d1-4f73-97b2-f7114af589f4",
      "data": {
        "name": "Temperature 1"
      },
      "metadata": {
        "createdAt": "2020-04-21T17:49:19+00:00",
        "createdBy": "ec1dcb7c-55ba-4af6-8359-4a75b01e0178",
        "updatedAt": "2020-04-21T17:49:19+00:00",
        "updatedBy": "ec1dcb7c-55ba-4af6-8359-4a75b01e0178"
      }
    },
    "d6cf3b59-3f03-40e2-bb52-821df2341b9f": {
      "@context": "https://standards.oftrust.net/v2/Context/Identity/Equipment/Device/Sensor/CarbonDioxideSensor/",
      "@type": "CarbonDioxideSensor",
      "@id": "d6cf3b59-3f03-40e2-bb52-821df2341b9f",
      "data": {
        "name": "CO2 1"
      },
      "metadata": {
        "createdAt": "2020-04-21T17:49:38+00:00",
        "createdBy": "ec1dcb7c-55ba-4af6-8359-4a75b01e0178",
        "updatedAt": "2020-04-21T17:49:38+00:00",
        "updatedBy": "ec1dcb7c-55ba-4af6-8359-4a75b01e0178"
      }
    },
    "288f1dc2-ade0-433b-abfe-1d485c34bbd9": {
      "@context": "https://standards.oftrust.net/v2/Context/Identity/Equipment/Device/Sensor/HumiditySensor/",
      "@type": "HumiditySensor",
      "@id": "288f1dc2-ade0-433b-abfe-1d485c34bbd9",
      "data": {
        "name": "Humidity 1"
      },
      "metadata": {
        "createdAt": "2020-04-21T17:50:33+00:00",
        "createdBy": "ec1dcb7c-55ba-4af6-8359-4a75b01e0178",
        "updatedAt": "2020-04-21T17:50:33+00:00",
        "updatedBy": "ec1dcb7c-55ba-4af6-8359-4a75b01e0178"
      }
    },
    "d31522b4-4225-4984-a3af-50929ca4e372": {
      "@context": "https://standards.oftrust.net/v2/Context/Identity/Equipment/Device/Sensor/TemperatureSensor/",
      "@type": "TemperatureSensor",
      "@id": "d31522b4-4225-4984-a3af-50929ca4e372",
      "data": {
        "name": "Temperature 3"
      },
      "metadata": {
        "createdAt": "2020-04-21T17:52:38+00:00",
        "createdBy": "ec1dcb7c-55ba-4af6-8359-4a75b01e0178",
        "updatedAt": "2020-04-21T17:52:38+00:00",
        "updatedBy": "ec1dcb7c-55ba-4af6-8359-4a75b01e0178"
      }
    },
    "d6f39184-f457-4818-90ee-ead5664dfa08": {
      "@context": "https://standards.oftrust.net/v2/Context/Identity/Equipment/Device/Sensor/CarbonDioxideSensor/",
      "@type": "CarbonDioxideSensor",
      "@id": "d6f39184-f457-4818-90ee-ead5664dfa08",
      "data": {
        "name": "CO2 2"
      },
      "metadata": {
        "createdAt": "2020-04-21T17:53:03+00:00",
        "createdBy": "ec1dcb7c-55ba-4af6-8359-4a75b01e0178",
        "updatedAt": "2020-04-21T17:53:03+00:00",
        "updatedBy": "ec1dcb7c-55ba-4af6-8359-4a75b01e0178"
      }
    }
  },
  "pagination": {
    "links": [
      {
        "rel": "first",
        "href": "https://api-sandbox.oftrust.net/identities/v1/discovery?offset=0&limit=20&linkContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FLink%2FBelongsTo%2F&fromId=170bb798-0f91-498d-8fa5-7b690cd1a1ca&identityContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FIdentity%2FDevice%2FSensor%2F&linkDirection=IN&maxDepth=5"
      },
      {
        "rel": "self",
        "href": "https://api-sandbox.oftrust.net/identities/v1/discovery?linkContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FLink%2FBelongsTo%2F&fromId=170bb798-0f91-498d-8fa5-7b690cd1a1ca&identityContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FIdentity%2FDevice%2FSensor%2F&linkDirection=IN&maxDepth=5"
      },
      {
        "rel": "last",
        "href": "https://api-sandbox.oftrust.net/identities/v1/discovery?offset=0&limit=20&linkContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FLink%2FBelongsTo%2F&fromId=170bb798-0f91-498d-8fa5-7b690cd1a1ca&identityContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FIdentity%2FDevice%2FSensor%2F&linkDirection=IN&maxDepth=5"
      }
    ],
    "hasMore": false,
    "totalCount": 5
  }
}

This result looks more accurate. However Identity API returns 5 identities of type Sensor, yet according to the scheme there should be 6. Let's try to find out where is one missing identity went.

Link context and direction

If your network is exactly as specified in the scheme, then one of Temperature Sensor should be connected to Apartment with LocatedAt Link type. Unfortunately, discovery feature does not support multiple values for linkContext parameter. Therefore, we can simply replace:

Request: GET /identities/v1/discovery

curl --request GET \
  --url 'https://api-sandbox.oftrust.net/identities/v1/discovery?linkContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FLink%2FLocatedAt%2F&fromId=170bb798-0f91-498d-8fa5-7b690cd1a1ca&identityContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FIdentity%2FDevice%2FSensor%2F&linkDirection=IN&maxDepth=5&=' \
  --header 'authorization: Bearer eyJ0eXAiOiS6QeagF0...9rmenc'

Response: Ok
Status: 200 OK
Body:

{
  "identities": {
    "7fe3ab03-7710-4666-97f8-f6dd18afa316": {
      "@context": "https://standards.oftrust.net/v2/Context/Identity/Equipment/Device/Sensor/TemperatureSensor/",
      "@type": "TemperatureSensor",
      "@id": "7fe3ab03-7710-4666-97f8-f6dd18afa316",
      "data": {
        "name": "Temperature 2"
      },
      "metadata": {
        "createdAt": "2020-04-21T17:51:10+00:00",
        "createdBy": "ec1dcb7c-55ba-4af6-8359-4a75b01e0178",
        "updatedAt": "2020-04-21T17:51:10+00:00",
        "updatedBy": "ec1dcb7c-55ba-4af6-8359-4a75b01e0178"
      }
    }
  },
  "pagination": {
    "links": [
      {
        "rel": "first",
        "href": "https://api-sandbox.oftrust.net/identities/v1/discovery?offset=0&limit=20&linkContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FLink%2FLocatedAt%2F&fromId=170bb798-0f91-498d-8fa5-7b690cd1a1ca&identityContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FIdentity%2FDevice%2FSensor%2F&linkDirection=IN&maxDepth=5"
      },
      {
        "rel": "self",
        "href": "https://api-sandbox.oftrust.net/identities/v1/discovery?linkContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FLink%2FLocatedAt%2F&fromId=170bb798-0f91-498d-8fa5-7b690cd1a1ca&identityContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FIdentity%2FDevice%2FSensor%2F&linkDirection=IN&maxDepth=5"
      },
      {
        "rel": "last",
        "href": "https://api-sandbox.oftrust.net/identities/v1/discovery?offset=0&limit=20&linkContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FLink%2FLocatedAt%2F&fromId=170bb798-0f91-498d-8fa5-7b690cd1a1ca&identityContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FIdentity%2FDevice%2FSensor%2F&linkDirection=IN&maxDepth=5"
      }
    ],
    "hasMore": false,
    "totalCount": 1
  }
}

Here it is one missing Temperature Sensor which is connected via LocatedAt link.

Link direction specifies which way a link connects two identities together. For discovery feature this is important, because all identities you want to iterate must be connected with Link type of specified in linkContext and direction specified in linkDirection.

NOTE: All identities must be connected with the same type of Link and direction. Specified in linkContext and linkDirection for discovery query.

Data products discovery

Data product is one of essential concepts of Platform of Trust. Discovery data products works pretty much the same way as discovery. Though it does one extra steps.

On practice Data Products are usually connected to related identities. E.g. Temperature sensors can produce measurement data which can be productized and attach to this very Sensor identity in a form of Data Product identity.

NOTE: You can still discover Data Product identity using identity discovery feature. However using data discovery feature will provide additional information for this particular Data Product identity.

Let's first create Data product and attach it to our identity.

small-network-product.jpg

Request: POST /products/v1/

curl --request POST \
  --url https://api-sandbox.oftrust.net/products/v1/ \
  --header 'authorization: Bearer eyJ0eXAiOiJKV1QiLC...enc' \
  --header 'content-type: application/json' \
  --data '{
    "dataContext": "https://standards.oftrust.net/v2/Context/DataProductOutput/?v=2.0",
    "productCode": "sensors-data-product",
    "parameterContext": "https://standards.oftrust.net/v2/Context/DataProductParameters/?v=2.0",
    "translatorUrl": "https://api.oftrust.local:32000/se-translator/v1/fetch-trends",
    "name": "Sensors data product",
    "groupId": "14622d5e-4897-4fe4-a463-04a9ad0cb736",
    "organizationPublicKeys": [
        {"type": "RsaSignature2018", "url": "https://api-sandbox.lifeengine.io/translator/v1/public.key"}
    ]
}'

Response: Ok
Status: 201 Created
Body:

{
  "@context": "https://standards.oftrust.net/v2/Context/Identity/Product/DataProduct/",
  "@type": "DataProduct",
  "@id": "https://api-sandbox.oftrust.net/products/v1/sensors-data-product",
  "productCode": "sensors-data-product",
  "dataContext": "https://standards.oftrust.net/v2/Context/DataProductOutput/?v=2.0",
  "parameterContext": "https://standards.oftrust.net/v2/Context/DataProductParameters/?v=2.0",
  "translatorUrl": "https://api.oftrust.local:32000/se-translator/v1/fetch-trends",
  "name": "Sensors data product",
  "organizationPublicKeys": [
    {
      "type": "RsaSignature2018",
      "url": "https://api-sandbox.oftrust.net/translator/v1/public.key"
    }
  ],
  "description": null,
  "imageUrl": null,
  "identityId": "7940fc74-d1df-442b-a59d-6ae16b2f659e"
}

Read more about GET /identities/v1/dataDiscovery request in Identity API

You can now use identityId value from returned data to link Sensors data product with one of the sensors. You can connect any Temperature Sensor to Data Product with AtDataProduct Link.

Let's now use Identity API and /dataDiscovery functionality to discover any Data product identities connected to the sensors.

Request: POST /products/v1/

curl --request GET \
  --url 'https://api-sandbox.oftrust.net/identities/v1/dataDiscovery?linkContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FLink%2FBelongsTo%2F&fromId=170bb798-0f91-498d-8fa5-7b690cd1a1ca&identityContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FIdentity%2FDevice%2FSensor%2FCarbonDioxideSensor%2F&linkDirection=IN&maxDepth=5&=' \
  --header 'authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...ciOiJSLWP9rmenc'

Response: Ok
Status: 201 Created
Body:

{
  "dataProducts": {
    "sensors-data-product": {
      "d6cf3b59-3f03-40e2-bb52-821df2341b9f": {}
    }
  },
  "pagination": {
    "links": [
      {
        "rel": "first",
        "href": "https://api-sandbox.oftrust.net/identities/v1/dataDiscovery?offset=0&limit=20&linkContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FLink%2FBelongsTo%2F&fromId=170bb798-0f91-498d-8fa5-7b690cd1a1ca&identityContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FIdentity%2FDevice%2FSensor%2FCarbonDioxideSensor%2F&linkDirection=IN&maxDepth=5"
      },
      {
        "rel": "self",
        "href": "https://api-sandbox.oftrust.net/identities/v1/dataDiscovery?linkContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FLink%2FBelongsTo%2F&fromId=170bb798-0f91-498d-8fa5-7b690cd1a1ca&identityContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FIdentity%2FDevice%2FSensor%2FCarbonDioxideSensor%2F&linkDirection=IN&maxDepth=5"
      },
      {
        "rel": "last",
        "href": "https://api-sandbox.oftrust.net/identities/v1/dataDiscovery?offset=0&limit=20&linkContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FLink%2FBelongsTo%2F&fromId=170bb798-0f91-498d-8fa5-7b690cd1a1ca&identityContext=https%3A%2F%2Fstandards.oftrust.net%2Fv1%2FContext%2FIdentity%2FDevice%2FSensor%2FCarbonDioxideSensor%2F&linkDirection=IN&maxDepth=5"
      }
    ],
    "hasMore": false,
    "totalCount": 1
  }
}

This request returns all Data Products connected to all Carbon Dioxide Sensor identities within reach of discovery query. Where sensors-data-product is a product name and d6cf3b59-3f03-40e2-bb52-821df2341b9f is ID of Sensor

NOTE: You can use Identity API and discovery feature to explore any Platform of Trust identities and access their information according to ACL.

Link data

When working with real Data Products, they often contain additional data which will be returned with /dataDiscovery response.

"dataProducts": {
    "sensors-data-product": {
      "d6cf3b59-3f03-40e2-bb52-821df2341b9f": {
        "capabilities": ["Temperature"],
        "maintainerId": "2792a819-d4a1-46bc-94b8-6ce7efa79db7",
        "stream": false 
      },
      "d6cf3b59-3f03-40e2-bb52-821df2341b9f": {
        "capabilities": ["CO2"],
        "maintainerId": "c06f43d2-ac22-492f-b0d5-90558ff3dea7",
        "stream": true
      }
    }
  }

This additional data is included into AtDataProduct Link that connects Data Product and Sensor. This data will be added by maintainers of that particular Data Product identity.

Custom Data Product context

By default Identity API returns only Data Product identities linked with AtDataProduct Link. If Data Product identity has different context, you can specify it with atDataProductContext query parameter.

Summary

Platform of Trust provides capability for users to explore and look up for identities in the network. Users can discover identities with /discovery request and also data products with /dataDiscovery that also provides some additional data.

Data discovery is an easy way to see which products are available to you in your network.

Create account and get started!

Create account and start utilizing the free and open Sandbox!

If you are integrating data and creating data products, take a look at the Data Product guide .

Digital identity (Identity) is fundamental concept of the platform, take a look at the Identities and Links guide .

Ready to explore more?

Try Platform of Trust Sandbox

Improvement Suggestions? or a New Guide?

Tell us in GitHub