Back to top
Vastuu Group

Identities and Links

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

Tags: V1 APIs, Identity, Link, Identity Network

This guide is for the developers who have registered to Platform of Trust and have gained basic knowledge about Platform features and terminologies. In this guide, we will show how to work with Identity and Link in order to create Identity network mimicking real-life physical objects and their relationships.

We will be using Platform of Trust Identity API V1 in this guide. You can check the API profile in our Developer Portal.

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. For example, here is the context for an Apartment type identity.
  • You have general knowledge of RESTful APIs.
  • You have a bearer token to access Platform of Trust APIs in the Sandbox environment.

Note: Keep in mind, that Version 1 APIs from Platform of Trust have been used in this demonstration.

Introduction

digital representations 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

– 

Identities

2 Identities of various types can be connected via a link to represent their actual relationship in the physical world. A chain of interconnected identities mimicking simple or complex relationship structures among real-life objects is called Identity network.

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

– 

Identity Network

At present, Platform of Trust has a large network of identities representing real-life objects associated with Build environments. Each identity has a set of attributes that are defined as its @context using JSON-LD schema.

Here is an HTTP response data when an identity of Apartment type is created

{
  "@context": "https://standards.oftrust.net/v2/Context/Identity/Space/Apartment/",
  "@type": "Apartment",
  "@id": "ec2d273b-b866-496e-b682-79b061dbf71f",
  "inLinks": [],
  "outLinks": [],
  "data": {
    "name": "Cozy place"
  },
  "metadata": {
    "createdAt": "2019-09-11T11:24:23+00:00",
    "createdBy": "33237067-e72c-4f26-b78b-9f9e234b2e7d",
    "updatedAt": "2019-09-11T11:24:23+00:00",
    "updatedBy": "33237067-e72c-4f26-b78b-9f9e234b2e7d"
  }
}

You can know more about Apartment type identity from its @context URL.

Also, our Ontology Viewer is the best place to know details about an identity's General Information, Vocabulary, Class Definition, JSON Schema and Data Example.

Create Identities

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.

Insomnia-Demo-Identity Network - Dontuse.jpg

NOTE: For ease of following, we'll limit creating and linking identities up to Sensor identities. Data Product creation is discussed in more detail in Data Product 101 guide.

To try out Identity API, you need to login to our Sandbox Environment and get the Bearer token.

Login to Sandbox

Request template to create a Building

curl -i --request POST \
  --url https://api-sandbox.oftrust.net/identities/v1 \
  --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9eyJzY29w...DVs5aaf' \
  --header 'content-type: application/json' \
  --data '{
    "@context": "https://standards.oftrust.net/v2/Context/Identity/Structure/Building/",
    "@type": "Building",
    "data": {
        "name": "Glass House"
    }
}'

To successfully send this request, you will need the following parameter(s):

  • Authorization: Bearer token of the format Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9eyJzY29w...DVs5aaf

And also some of data must be specified:

  • @context: URL of JSON-LD file containing information needed to create the identity
  • @type: type of the identity. In this case, it is Building
  • name: human-friendly name for the identity

Read more about /identities/v1 request in Identity API

On success, you will receive something similar to the following:

Response: OK
Status: 201 Created
Body:

{
  "@context": "https://standards.oftrust.net/v2/Context/Identity/Structure/Building/",
  "@type": "Building",
  "@id": "ec2d273b-b866-496e-b682-79b061dbf71f",
  "inLinks": [],
  "outLinks": [],
  "data": {
    "name": "Glass House"
  },
  "metadata": {
    "createdAt": "2019-09-11T11:24:23+00:00",
    "createdBy": "33237067-e72c-4f26-b78b-9f9e234b2e7d",
    "updatedAt": "2019-09-11T11:24:23+00:00",
    "updatedBy": "33237067-e72c-4f26-b78b-9f9e234b2e7d"
  }
}

From the response, the most important attribute is the @id of the created identity. This can be used to

  • read the information on any identity you have access to
  • create a link with another identity

NOTE: Make sure to save @ids of the identities you create for further use.

Other new and interesting fields are inLinks and outLinks. Right now they both are empty, but let's see what happens when we create more identities and links between them.

Let's create identities of type Floor, Room and Sensor

Request template for creating Floor identity

curl -i --request POST \
  --url https://api-sandbox.oftrust.net/identities/v1 \
  --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9eyJzY29w...DVs5aaf' \
  --header 'content-type: application/json' \
  --data '{
    "@context": "https://standards.oftrust.net/v2/Context/Identity/Element/BuildingElement/Floor/",
    "@type": "Floor",
    "data": {
        "name": "Floor 1"
    }
}'

Request template for creating Room identity

curl -i --request POST \
  --url https://api-sandbox.oftrust.net/identities/v1 \
  --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9eyJzY29w...DVs5aaf' \
  --header 'content-type: application/json' \
  --data '{
    "@context": "https://standards.oftrust.net/v2/Context/Identity/Space/Room/",
    "@type": "Room",
    "data": {
        "name": "Bedroom"
    }
}'

Request template for creating Temperature Sensor identity

curl -i --request POST \
  --url https://api-sandbox.oftrust.net/identities/v1 \
  --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9eyJzY29w...DVs5aaf' \
  --header 'content-type: application/json' \
  --data '{
    "@context": "https://standards.oftrust.net/v2/Context/Identity/Equipment/Device/Sensor/TemperatureSensor/",
    "@type": "TemperatureSensor",
    "data": {
        "name": "Bedroom-temperature"
    }
}'

NOTE: **NOTE:** For creating a "CarbonDioxidesensor" `type` sensor you should use this context URL: https://standards.oftrust.net/v2/Context/Identity/Equipment/Device/Sensor/CarbonDioxideSensor/

Contexts of different sensor types can be accessed from here.

After executing the cURL requests provided this section, you should have created at least 4 different types of identities: Building, Floor, Room and Temperature Sensor.

View Created Identities

Using Identity API, you can read information about identities in Platform of Trust. Anyone with a Bearer token can read an identity if s/he knows the @id associated with it. For security purpose, a user can only read identities s/he has created or has been grant access to.

Let's try to read the Temperature Sensor identity we created in the previous step.

Request template for reading an Identity

curl -i --request GET \
  --url https://api-sandbox.oftrust.net/identities/v1/{identityId} \
  --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9eyJzY29w...DVs5aaf'

The parameter(s) are:

  • identityId: @id of the "TemperatureSensor"
  • Authorization: Bearer token of the format Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9eyJzY29w...DVs5aaf

On success, you will receive something similar to the following:

Response: Ok
Status: 200 OK
Body:

{
   "@context":"https://standards.oftrust.net/v2/Context/Identity/Equipment/Device/Sensor/TemperatureSensor/",
   "@type":"TemperatureSensor",
   "@id":"59c3d8b9-0881-49dd-92b5-582a7a941109",
   "data":{
      "name":"Thermometer"
   },
   "metadata":{
      "createdAt":"2020-03-30T09:05:02+00:00",
      "createdBy":"01725951-3bd4-4c6f-875c-df1d07d7120f",
      "updatedAt":"2020-03-30T09:05:02+00:00",
      "updatedBy":"01725951-3bd4-4c6f-875c-df1d07d7120f"
   },
   "inLinks":[

   ],
   "pagination":{
      "inLinks":{
         "links":[
            {
               "rel":"first",
               "href":"https://api-sandbox.oftrust.net/identities/v1/59c3d8b9-0881-49dd-92b5-582a7a941109?offset=0&limit=100"
            },
            {
               "rel":"self",
               "href":"https://api-sandbox.oftrust.net/identities/v1/59c3d8b9-0881-49dd-92b5-582a7a941109"
            },
            {
               "rel":"last",
               "href":"https://api-sandbox.oftrust.net/identities/v1/59c3d8b9-0881-49dd-92b5-582a7a941109?offset=0&limit=100"
            }
         ],
         "hasMore":false,
         "totalCount":0
      },
      "outLinks":{
         "links":[
            {
               "rel":"first",
               "href":"https://api-sandbox.oftrust.net/identities/v1/59c3d8b9-0881-49dd-92b5-582a7a941109?offset=0&limit=100"
            },
            {
               "rel":"self",
               "href":"https://api-sandbox.oftrust.net/identities/v1/59c3d8b9-0881-49dd-92b5-582a7a941109"
            },
            {
               "rel":"last",
               "href":"https://api-sandbox.oftrust.net/identities/v1/59c3d8b9-0881-49dd-92b5-582a7a941109?offset=0&limit=100"
            }
         ],
         "hasMore":false,
         "totalCount":1
      }
   },
   "outLinks":[
      {
         "@context":"https://standards.oftrust.net/v2/Context/Link/BelongsTo/",
         "@type":"BelongsTo",
         "@id":"b2275147-d8f7-4ed9-b631-5426ec2ccb65",
         "from":"59c3d8b9-0881-49dd-92b5-582a7a941109",
         "to":"105a857b-1e8d-4b8d-a724-2e759bdbfac6",
         "data":{

         },
         "metadata":{
            "createdAt":"2020-03-30T09:41:34+00:00",
            "createdBy":"01725951-3bd4-4c6f-875c-df1d07d7120f",
            "updatedAt":"2020-03-30T09:41:34+00:00",
            "updatedBy":"01725951-3bd4-4c6f-875c-df1d07d7120f"
         }
      }
   ]
}

As you can see, the response contains the same data we provided while creating the Temperature Sensor.

Feel free to try out the same request for other identities you have created so far. You can also try it out on identities for which you know @id and have access to.

NOTE: In the response, you can see data related to outLinks for the identity. We'll discuss it in the Exploring Identities, inLinks and outLinks section.

Create Links between Identities

Connects two identities to establish a meaningful relationship between the identities.

– 

Link

Just like in real-world all things are connected, all identities in Platform of Trust should be connected. You can create a link between 2 identities with a request similar in certain ways to the requests that you were using to create new identities.

Let's try creating a link between the Room and Temperature Sensor identities.

Request template to create a Link between two Identities

curl -i --request POST \
  --url https://api-sandbox.oftrust.net/identities/v1/{fromIdentityId}/link/{toIdentityId} \
  --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9eyJzY29w...DVs5aaf' \
  --header 'content-type: application/json' \
  --data '{
  "@context": "https://standards.oftrust.net/v2/Context/Link/BelongsTo/",
  "@type": "BelongsTo"
}'

The parameter(s) are:

  • fromIdentityId: @id of the identity from which the link will originate. In this case, here it is the @id of the Temperature Sensor.
  • toIdentityId: @id of the identity at which the link will terminate. In this case, here it is the @id of the room.
  • Authorization: Bearer token of the format Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9eyJzY29w...DVs5aaf

Some data needed to specify is:

  • context: URL of JSON-LD file containing information needed to create the identity.
  • type: type of the link. In this case, it is BelongsTo.

NOTE: You can read more about link types and link contexts from our Ontology Viewer

On success, you will receive something similar to the following:

Response: OK
Status: 201 Created
Body:

{
  "@context":"https://standards.oftrust.net/v2/Context/Link/BelongsTo/",
  "@type": "BelongsTo",
  "@id": "be7a2c57-03d8-46f4-aaf0-2b1ca118ef5c",
  "from": "8ac7494b-b7bc-4a63-a253-4b9b1887b262",
  "to": "a6b5a74e-bd98-4c9b-9561-932877258833",
  "data": {},
  "metadata": {
    "createdAt": "2019-09-12T09:49:24+00:00",
    "createdBy": "33237067-e72c-4f26-b78b-9f9e234b2e7d",
    "updatedAt": "2019-09-12T09:49:24+00:00",
    "updatedBy": "33237067-e72c-4f26-b78b-9f9e234b2e7d"
  }
}

Now, the Temperature Sensor identity is connected to Room identity with a BelongsTo type link.

Temperature Sensor --BelongsTo--> Room.

Let's try to connect the Room identity with the floor identity. We'll be establishing the following relationship:

Room --BelongsTo--> Floor

curl -i --request POST \
  --url https://api-sandbox.oftrust.net/identities/v1/{roomIdentityId}/link/{floorIdentityId} \
  --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9eyJzY29w...DVs5aaf' \
  --header 'content-type: application/json' \
  --data '{
  "@context": "https://standards.oftrust.net/v2/Context/Link/BelongsTo/",
  "@type": "BelongsTo"
}'

On success, we'll now have three identities connected together:

Temperature Sensor --BelongsTo--> Room --BelongsTo--> Floor

Linking identities is a great feature which is used throughout Platform of Trust. This allows users and developers to assign and explore relations, discover new identities, manage access control rights, etc.

Exploring Identities, inLinks and outLinks

We have already learnt how to read a particular identity by its @id. Let's see how the data has changed after we linked a couple of identities together in the previous step.

Let's read the Room identity.

curl -i --request GET \
  --url https://api-sandbox.oftrust.net/identities/v1/{identityId} \
  --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9eyJzY29w...DVs5aaf'

The parameter(s) are:

  • identityId: @id of the "Room"
  • Authorization: Bearer token of the format Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9eyJzY29w...DVs5aaf

If the request is successful and you have followed the previous steps described in this guide, you should be able to see something similar:

Response: OK
Status: 200 OK
Body:

{
   "@context":"https://standards.oftrust.net/v2/Context/Identity/Space/Room/",
   "@type":"Room",
   "@id":"9ff0c487-a470-4935-ac44-653149cac21d",
   "data":{
      "name":"Bedroom"
   },
   "metadata":{
      "createdAt":"2020-05-11T09:42:02+00:00",
      "createdBy":"01725951-3bd4-4c6f-875c-df1d07d7120f",
      "updatedAt":"2020-05-11T09:42:02+00:00",
      "updatedBy":"01725951-3bd4-4c6f-875c-df1d07d7120f"
   },
   "inLinks":[
      {
         "@context":"https://standards.oftrust.net/v2/Context/Link/BelongsTo/",
         "@type":"BelongsTo",
         "@id":"69d71432-261e-419d-9778-39d1da2f5190",
         "from":"e954123e-53fb-4e1a-888b-ab686bc0f3d3",
         "to":"9ff0c487-a470-4935-ac44-653149cac21d",
         "data":{

         },
         "metadata":{
            "createdAt":"2020-05-11T10:16:49+00:00",
            "createdBy":"01725951-3bd4-4c6f-875c-df1d07d7120f",
            "updatedAt":"2020-05-11T10:16:49+00:00",
            "updatedBy":"01725951-3bd4-4c6f-875c-df1d07d7120f"
         }
      }
   ],
   "pagination":{
      "inLinks":{
         "links":[
            {
               "rel":"first",
               "href":"https://api-sandbox.oftrust.net/identities/v1/9ff0c487-a470-4935-ac44-653149cac21d?offset=0&limit=100"
            },
            {
               "rel":"self",
               "href":"https://api-sandbox.oftrust.net/identities/v1/9ff0c487-a470-4935-ac44-653149cac21d"
            },
            {
               "rel":"last",
               "href":"https://api-sandbox.oftrust.net/identities/v1/9ff0c487-a470-4935-ac44-653149cac21d?offset=0&limit=100"
            }
         ],
         "hasMore":false,
         "totalCount":1
      },
      "outLinks":{
         "links":[
            {
               "rel":"first",
               "href":"https://api-sandbox.oftrust.net/identities/v1/9ff0c487-a470-4935-ac44-653149cac21d?offset=0&limit=100"
            },
            {
               "rel":"self",
               "href":"https://api-sandbox.oftrust.net/identities/v1/9ff0c487-a470-4935-ac44-653149cac21d"
            },
            {
               "rel":"last",
               "href":"https://api-sandbox.oftrust.net/identities/v1/9ff0c487-a470-4935-ac44-653149cac21d?offset=0&limit=100"
            }
         ],
         "hasMore":false,
         "totalCount":1
      }
   },
   "outLinks":[
      {
         "@context":"https://standards.oftrust.net/v2/Context/Link/BelongsTo/",
         "@type":"BelongsTo",
         "@id":"ac59abdc-6d28-4b50-a2fe-36902e4904b4",
         "from":"9ff0c487-a470-4935-ac44-653149cac21d",
         "to":"b4974687-226a-4d4f-a8b7-9d918099e42e",
         "data":{

         },
         "metadata":{
            "createdAt":"2020-05-11T10:56:45+00:00",
            "createdBy":"01725951-3bd4-4c6f-875c-df1d07d7120f",
            "updatedAt":"2020-05-11T10:56:45+00:00",
            "updatedBy":"01725951-3bd4-4c6f-875c-df1d07d7120f"
         }
      }
   ]
}

The Room identity has both outLinks and inLinks data. inLinks originate from other identities and terminate to the identity we are currently reading. outLinks originate from the identity we are currently reading and terminate to other identities.

In this example, the identity Room has an inLink of type BelongsTo from the identity e954123e-53fb-4e1a-888b-ab686bc0f3d3, which if send a read request to Identity API, would be the identity Temperature Sensor. Hence the direction is "From Temperature Sensor to the Room"

Room also has an outLink of type BelongsTo to the identity b4974687-226a-4d4f-a8b7-9d918099e42e, which if send a read request to Identity API, would be the identity Floor. Hence the direction is "From the Room to the Floor"

outLinks and inLinks contain all connections that users have permission to see.

GET response from read an identity request contains pagination information for both inLinks and outLinks, total number of inLinks and outLinks. When there are different types of links exist, eg. BelongsTo, DataProductAt, etc., depending on their direction, each of those are shown separately under inLinks and outLinks attributes.

You can also request only for links of a certain identity at a time.

Request template to only read links of an identity

curl -i --request GET \
  --url https://api-sandbox.oftrust.net/identities/v1/{identityId}/links \
  --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9eyJzY29w...DVs5aaf'

The parameter(s) are:

  • identityId: @id of the identity
  • Authorization: Bearer token of the format Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9eyJzY29w...DVs5aaf

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.

In a nutshell, part of the identity network should be something similar to this:

Temperature Data Product <--AtDataProduct-- Temperature Sensor --BelongTo--> Room

Update Identities and Links

Updating an identity as easy as creating a new one. You should be able to update any identity that you created yourself. For updating other identities not created by yourself, you need to have certain permissions.

Let's update the sensor we created previously.

Request template for updating an identity

curl -i --request PUT \
  --url https://api-sandbox.oftrust.net/identities/v1/{identityId} \
  --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9eyJzY29w...DVs5aaf' \
  --header 'content-type: application/json' \
  --data '{
    "@context": "https://standards.oftrust.net/v2/Context/Identity/Equipment/Device/Sensor/TemperatureSensor/",
    "@type": "TemperatureSensor",
    "data": {
        "name": "THE Best sensor 10000!",
        "colorName": "Blue",
        "descriptionGeneral": "This sensor does its job!"
    }
}'

The parameter(s) are:

  • identityId: @id of the identity. In this case, it is the @id of the Temperature Sensor
  • Authorization: Bearer token of the format Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9eyJzY29w...DVs5aaf

Some data needed to specify are:

  • context: URL of JSON-LD file containing information needed for the specific identity.
  • type: type of the identity. In this case, it is Temperature Sensor,
  • data: information that you want to update about the identity. In this case, we are adding some attributes like colorName, descriptionGeneral, etc.

NOTE: You can add any attributes as data for an identity as long as they don't match Platform of Trust reserved keywords.

On success, you should receive a response similar to this:

Response: OK
Status: 200 OK
Body:

{
   "@context":"https://standards.oftrust.net/v2/Context/Identity/Equipment/Device/Sensor/TemperatureSensor/",
   "@type":"TemperatureSensor",
   "@id":"e954123e-53fb-4e1a-888b-ab686bc0f3d3",
   "data":{
      "name":"THE Best sensor 10000!",
      "colorName":"Blue",
      "descriptionGeneral":"This sensor does its job!"
   },
   "metadata":{
      "createdAt":"2020-05-07T11:40:04+00:00",
      "createdBy":"01725951-3bd4-4c6f-875c-df1d07d7120f",
      "updatedAt":"2020-05-11T12:00:47+00:00",
      "updatedBy":"01725951-3bd4-4c6f-875c-df1d07d7120f"
   },
   "inLinks":[

   ],
   "outLinks":[
      {
         "@context":"https://standards.oftrust.net/v2/Context/Link/BelongsTo/",
         "@type":"BelongsTo",
         "@id":"69d71432-261e-419d-9778-39d1da2f5190",
         "from":"e954123e-53fb-4e1a-888b-ab686bc0f3d3",
         "to":"9ff0c487-a470-4935-ac44-653149cac21d",
         "data":{

         },
         "metadata":{
            "createdAt":"2020-05-11T10:16:49+00:00",
            "createdBy":"01725951-3bd4-4c6f-875c-df1d07d7120f",
            "updatedAt":"2020-05-11T10:16:49+00:00",
            "updatedBy":"01725951-3bd4-4c6f-875c-df1d07d7120f"
         }
      }
   ]
}

The response contains the updated information you sent via the PUT request.

Similarly, you can update information associated with a link between two identities.

Request template to update link information

curl -i --request PUT \
  --url http://api-sandbox.oftrust.net/identities/v1/{fromIdentityId}/link/{toIdentityId}/{linkType} \
  --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9eyJzY29w...DVs5aaf'
  --data '{
    "@context": "https://standards.oftrust.net/v2/Context/Link/BelongsTo/",
    "@type": "BelongsTo",
    "data": {
        "name": "Link connecting room & sensor",
        "colorName": "Blue",
        "descriptionGeneral": "Its a BelongTo type link!"
    }
}'

Delete an Identity

Let's first try to delete the Temperature Sensor identity we created previously:

Request template to delete an identity

curl -i --request DELETE \
  --url https://api-sandbox.oftrust.net/identities/v1/{identityId} \
  --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9eyJzY29w...DVs5aaf'

The parameter(s) are:

  • identityId: @id of the identity. In this case, it is the @id of the Temperature Sensor
  • Authorization: Bearer token of the format Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9eyJzY29w...DVs5aaf

If you have executed all the request that the guide has provided so far, you should get a response similar to this:

{
   "error":{
      "status":422,
      "message":"Could not delete identity, reason: links exist to or from the identity."
   }
}

As you can see, Temperature Sensor identity can't be deleted. The reason is specified in the response, that "links exist to or from the identity.". In this case, a link of type BelongsTo exists from Room to Temperature Sensor.

Temperature Sensor --BelongTo--> Room

So deleting an identity involves Three steps:

  1. List all links of an identity.
  2. Delete all link types from and to that identity.
  3. Delete the identity itself.

Let's list all the links the Temperature Sensor has:

curl -i --request GET \
  --url https://api-sandbox.oftrust.net/identities/v1/{temperatureSensorIdentityId}/links \
  --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9eyJzY29w...DVs5aaf'

Response: OK
Status: 200 OK
Body:

{
   "inLinks":[

   ],
   "outLinks":[
      {
         "@context":"https://standards.oftrust.net/v2/Context/Link/BelongsTo/",
         "@type":"BelongsTo",
         "@id":"69d71432-261e-419d-9778-39d1da2f5190",
         "from":"e954123e-53fb-4e1a-888b-ab686bc0f3d3",
         "to":"9ff0c487-a470-4935-ac44-653149cac21d",
         "data":{

         },
         "metadata":{
            "createdAt":"2020-05-11T10:16:49+00:00",
            "createdBy":"01725951-3bd4-4c6f-875c-df1d07d7120f",
            "updatedAt":"2020-05-11T10:16:49+00:00",
            "updatedBy":"01725951-3bd4-4c6f-875c-df1d07d7120f"
         }
      }
   ],
   "pagination":{
      "inLinks":{
         "links":[
            {
               "rel":"first",
               "href":"https://api-sandbox.oftrust.net/identities/v1/e954123e-53fb-4e1a-888b-ab686bc0f3d3/links?offset=0&limit=100"
            },
            {
               "rel":"self",
               "href":"https://api-sandbox.oftrust.net/identities/v1/e954123e-53fb-4e1a-888b-ab686bc0f3d3/links"
            },
            {
               "rel":"last",
               "href":"https://api-sandbox.oftrust.net/identities/v1/e954123e-53fb-4e1a-888b-ab686bc0f3d3/links?offset=0&limit=100"
            }
         ],
         "hasMore":false,
         "totalCount":0
      },
      "outLinks":{
         "links":[
            {
               "rel":"first",
               "href":"https://api-sandbox.oftrust.net/identities/v1/e954123e-53fb-4e1a-888b-ab686bc0f3d3/links?offset=0&limit=100"
            },
            {
               "rel":"self",
               "href":"https://api-sandbox.oftrust.net/identities/v1/e954123e-53fb-4e1a-888b-ab686bc0f3d3/links"
            },
            {
               "rel":"last",
               "href":"https://api-sandbox.oftrust.net/identities/v1/e954123e-53fb-4e1a-888b-ab686bc0f3d3/links?offset=0&limit=100"
            }
         ],
         "hasMore":false,
         "totalCount":1
      }
   }
}

From the above response, we can get the @id and the type of the link from Temperature Sensor to the Room, which in this case are: 69d71432-261e-419d-9778-39d1da2f5190 and BelongsTo.

Now, let's delete this link.

Request template for deleting a link

curl -i --request DELETE \
  --url http://api-sandbox.oftrust.net/identities/v1/{fromIdenityId}/link/{toIdentityId}/{linkType} \
  --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9eyJzY29w...DVs5aaf'

The parameter(s) are:

  • fromIdenityId: @id of the identity where the link originates from. In this case, it is the @id of the Temperature Sensor
  • toIdentityId: @id of the identity where the link terminates to. In this case, it is the @id of the Room
  • linkType: links of a specific type you want to delete. In this case, it is BelongsTo
  • Authorization: Bearer token of the format Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9eyJzY29w...DVs5aaf

On success, you will receive a response similar to this:

HTTP/1.0 204 No Content

You can again make a cURL request to read the Temperature Sensor identity and you will see no outLinks or inLinks exists there.

Finally, let's delete the Temperature Sensor identity.

curl -i --request DELETE \
  --url https://api-sandbox.oftrust.net/identities/v1/{temperatureSensorIdentityId} \
  --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9eyJzY29w...DVs5aaf'

On success, you will receive a response similar to this:

HTTP/1.0 204 No Content

To verify, try to read again the Temperature Sensor identity with its @id. You will receive a response similar to this:

Response: Not Found
Status: 404 Not Found
body:

{
   "error":{
      "status":404,
      "message":"Identity 'e954123e-53fb-4e1a-888b-ab686bc0f3d3' not found."
   }
}

Which indicates, the Temperature Sensor no longer exists in your identity network

Conclusion

Congratulations! Now you have gained detailed knowledge on Platform of Trust terminologies: Identities, Links and Identity Network. Acquiring knowledge about their know-hows is important to generate harmonized data flow between identities to create a complex and multiplex Identity Network. With the aid of Identity API, now you will be able to create and modify from very simple to very robust identity network.

Recommended Actions

Learn about the Discovery Feature in Identity API in our guide Identity and Data Discovery

Learn about Data Products and How to Consume Harmonized Data .

Create an account and try out Platform of Trust features in our Sandbox

Ready to explore more?

Try Platform Sandbox

Improvement Suggestions? or a New Guide?

Tell us in GitHub