Setting up a Digital Twin

On this page we'll cover the creation and deployment of a Digital Twin with the Iotics API.

You can see the entire Iotics API Reference here.

Set your headers

The headers are an important part of your API request, representing the meta-data of your request. Before submitting a request you need to ensure you have set your headers:

Header	Type	Description	Mandatory
`Iotics-ClientRef`	String	Applies to all requests and solicited responses modelled as list to allow clients to represent the ref as a linked set of elements we will be using this to map to internal queues and provide namespace scopes	Optional
`Iotics-ClientAppId`	String	Applies to requests to provide a namespace for the application within which all the requests/responses are grouped irrespective of the clientRef	Mandatory
`Iotics-TransactionRef`	String	Used to loosely link requests/responses in a distributed environment each layer can add its own id to the list. Transaction ref is limited to a max of 16 elements per list and, for each list item, a max length of 36 characters	Optional
`Iotics-ConsumerGroup`	String	Consumer group, for group listener	Optional

The Post request

To create new Digital Twins you need to make a POST request to the Iotics API's Entity Service. Your request will need to provide the below payload parameters.

You can see an example of a POST request here.

Body parameters

The payload in your request will be made up of:

Parameter	Type	Description
`twinId`	Object	TwinID is a unique twin identifier.
`twinId:value`	String	Twin Identifier (using DID format)

Viewing your Twin

Now that you've created a Twin you can make a GET request to see your Twin.

You can see an example of a GET request here.

Path parameters

The path tells the API which Twin you are accessing and is made up of:

Parameter	Type	Description
`twinId`	String	The unique ID of the Twin set during your `POST` request

Query parameters

Defines the language code for labels and comments in the Twin.

Parameter	Type	Description
lang	String	Language code for labels and comments

Populating your Twin

To populate your Twin with data you need to send a PATCH request to the API. You just need to provide one or more of the below fields to be updated.

You can see an example of a PATCH request here.

Path parameters

The path tells the API which Digital Twin you are accessing and is made up of:

Parameter	Type	Description
`twinId`	String	The unique ID of the Twin set during your `POST` request

Body parameters

The body of your request defines what you're updating. You can update these parameters:

🚧
Note
Changes are applied in this order:

Tags

Visibility

Properties

Labels

Comments

Location

Comments

Allows you to add or delete comments on your Twin.

Parameter	Type	Description
`comments`	Object	Used to add a comment to your Twin
`comments:added`	Array of objects	List of the comments to be added to your Twin
`comments:added:lang`	String	The 2- character language code for your comment
`comments:added:value`	String	The comment to be added to your Twin
`comments:deletedByLang`	Array of objects	The 2- character language codes to be removed from your comments

Labels

Allows you to add or delete labels on your Twin.

Parameter	Type	Description
`labels`	Object	Used to add a label to your Twin
`labels:added`	Array of objects	List of the comments to be added to your Twin
`labels:added:lang`	String	The 2- character language code for your label
`labels:added:value`	String	The label to be added to your Twin
`labels:deletedByLang`	Array of objects	The 2- character language codes to be removed from your labels

Location

Allows you to add or delete a locations on your Twin.

Parameter	Type	Description
`location`	Object	Used to add a location to your Twin
`location:location`	Object	The location being added
`location:location:lat`	Double	The latitude of the location being added
`location:location:lon`	Double	The longitude of the location being added

newVisibility

Sets the visibility of the Twin to Private or Public.

Parameter	Type	Description
`newVisibility`	Object	Used to set the visibility of your Twin
`newVisibility:Visibility`	String	`PRIVATE` or `PUBLIC`

Properties

When you are updating the properties, you can(in order of operations):

Clear all properties
Delete a property
Delete properties by key
Add properties

A property is made up of one key and one value. The value can be one of:

langLiteralValue
literalValue
stringLiteralValue
uriValue

🚧
Note
One choose one type of value for the property.

Parameter	Type	Description
`properties`	Object	Used to give your Twin properties
`properties:added`	Array of objects	The properties being added
`properties:added:key`	String	The key (predicate) of the property
`properties:added:langLiteralValue`	Object	Use a langLiteralValue to add a property
`properties:added:langLiteralValue:lang`	String	The 2- character language code for your property
`properties:added:langLiteralValue:value`	String	The value of the property you're adding
`properties:added:literalValue`	Object	Use a literalValue to add a property
`properties:added:literalValue:dataType`	String	XSD data type. Currently supports: dateTime, time, date, boolean, integer, nonPositiveInteger, negativeInteger, nonNegativeInteger, positiveInteger, long, unsignedLong, int, unsignedInt, short, unsignedShort, byte, unsignedByte, anyURI
`properties:added:literalValue:value`	String	String representation of the value according to XSD datatype specification
`properties:added:stringLiteralValue`	Object	Use a stringLiteralValue to add a property
`properties:added:stringLiteralValue:value`	String	The value of the property you're adding
`properties:added:uriValue`	Object	Use a URI to add a property
`properties:added:uriValue:value`	String	The value of the property you're adding
`properties:clearedAll`	Boolean	Delete all properties currently set on the entity.
`properties:deleted`	Array of objects	Delete specific exact properties (by key and value). This operation is ignored if clearAll is True.
`properties:deleted:key`	String	The key (predicate) of the property
`properties:deleted:langLiteralValue`	Object	Use a langLiteralValue to delete a property
`properties:deleted:langLiteralValue:lang`	String	The 2- character language code for your property
`properties:deleted:langLiteralValue:value`	String	The value of the property you're deleting
`properties:deleted:literalValue`	Object	Use a literalValue to delete a property
`properties:deleted:literalValue:dataType`	String	XSD data type. Currently supports: dateTime, time, date, boolean, integer, nonPositiveInteger, negativeInteger, nonNegativeInteger, positiveInteger, long, unsignedLong, int, unsignedInt, short, unsignedShort, byte, unsignedByte, anyURI
`properties:deleted:literalValue:value`	String	string representation of the value according to XSD datatype specification
`properties:deleted:stringLiteralValue`	Object	Use a stringLiteral to delete a property
`properties:deleted:stringLiteralValue:value`	String	The value of the property you're deleting
`properties:deleted:uriValue`	Object	Use a URI to delete a property
`properties:deleted:uriValue:value`	String	The value of the property you're adding
`properties:deletedByKey`	Array of strings	Delete any properties with the given keys (predicates). This operation is ignored if clearAll is True

Parameter	Type	Description
`tags`	Object	Changes the tags on a Twin
`tags:added`	Array of strings	List of tags to be added
`tags:deleted`	Array of strings	List of tags to be deleted

Examples

Example POST request

This is an example of a POST request to create a new Twin:

curl --request POST \
  --url https:///qapi/twins \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Iotics-ClientAppId: ExampleAppID' \
  --header 'Iotics-ClientRef: ExampleRef' \
  --data '{"twinId":{"value":"did:iotics:iotVNNQJc4bVQjDuMDThZqW7cd664VQGUvCT"}}'

const fetch = require('node-fetch');

const url = 'https:///qapi/twins';

const options = {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'Iotics-ClientRef': 'ExampleRef',
    'Iotics-ClientAppId': 'ExampleAppID',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({twinId: {value: 'did:iotics:iotVNNQJc4bVQjDuMDThZqW7cd664VQGUvCT'}})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https:///qapi/twins")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["Accept"] = 'application/json'
request["Iotics-ClientRef"] = 'ExampleRef'
request["Iotics-ClientAppId"] = 'ExampleAppID'
request["Content-Type"] = 'application/json'
request.body = "{\"twinId\":{\"value\":\"did:iotics:iotVNNQJc4bVQjDuMDThZqW7cd664VQGUvCT\"}}"

response = http.request(request)
puts response.read_body

const options = {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'Iotics-ClientRef': 'ExampleRef',
    'Iotics-ClientAppId': 'ExampleAppID',
    'Content-Type': 'application/json'
  },
  body: '{"twinId":{"value":"did:iotics:iotVNNQJc4bVQjDuMDThZqW7cd664VQGUvCT"}}'
};

fetch('https:///qapi/twins', options)
  .then(response => console.log(response))
  .catch(err => console.error(err));

import requests

url = "https:///qapi/twins"

payload = {"twinId": {"value": "did:iotics:iotVNNQJc4bVQjDuMDThZqW7cd664VQGUvCT"}}
headers = {
    "Accept": "application/json",
    "Iotics-ClientRef": "ExampleRef",
    "Iotics-ClientAppId": "ExampleAppID",
    "Content-Type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

Example GET request

This is an example of a GET request to searching for the Twin created in the POST example:

curl --request GET \
  --url https:///qapi/twins/did%3Aiotics%3AiotVNNQJc4bVQjDuMDThZqW7cd664VQGUvCT \
  --header 'Accept: application/json' \
  --header 'Iotics-ClientAppId: ExampleAppID' \
  --header 'Iotics-ClientRef: ExampleRef'

const fetch = require('node-fetch');

const url = 'https:///qapi/twins/did%3Aiotics%3AiotVNNQJc4bVQjDuMDThZqW7cd664VQGUvCT';

const options = {
  method: 'GET',
  headers: {
    Accept: 'application/json',
    'Iotics-ClientRef': 'ExampleRef',
    'Iotics-ClientAppId': 'ExampleAppID'
  }
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https:///qapi/twins/did%3Aiotics%3AiotVNNQJc4bVQjDuMDThZqW7cd664VQGUvCT")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["Accept"] = 'application/json'
request["Iotics-ClientRef"] = 'ExampleRef'
request["Iotics-ClientAppId"] = 'ExampleAppID'

response = http.request(request)
puts response.read_body

const options = {
  method: 'GET',
  headers: {
    Accept: 'application/json',
    'Iotics-ClientRef': 'ExampleRef',
    'Iotics-ClientAppId': 'ExampleAppID'
  }
};

fetch('https:///qapi/twins/did%3Aiotics%3AiotVNNQJc4bVQjDuMDThZqW7cd664VQGUvCT', options)
  .then(response => console.log(response))
  .catch(err => console.error(err));

import requests

url = "https:///qapi/twins/did%3Aiotics%3AiotVNNQJc4bVQjDuMDThZqW7cd664VQGUvCT"

headers = {
    "Accept": "application/json",
    "Iotics-ClientRef": "ExampleRef",
    "Iotics-ClientAppId": "ExampleAppID"
}

response = requests.request("GET", url, headers=headers)

print(response.text)

Example PATCH request

This is an example PATCH request updating the Twin created and found in the previous examples:

curl --request PATCH \
  --url https:///qapi/twins/did%3Aiotics%3AiotVNNQJc4bVQjDuMDThZqW7cd664VQGUvCT \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Iotics-ClientAppId: ExampleAppID' \
  --header 'Iotics-ClientRef: ExampleRef' \
  --data '{"comments":{"added":[{"lang":"en","value":"Example comment"}]},"newVisibility":{"visibility":"PUBLIC"},"properties":{"added":[{"langLiteralValue":{"lang":"en","value":"Example Property Value"},"literalValue":{},"stringLiteralValue":{},"uriValue":{}}]}}'

const fetch = require('node-fetch');

const url = 'https:///qapi/twins/did%3Aiotics%3AiotVNNQJc4bVQjDuMDThZqW7cd664VQGUvCT';

const options = {
  method: 'PATCH',
  headers: {
    Accept: 'application/json',
    'Iotics-ClientRef': 'ExampleRef',
    'Iotics-ClientAppId': 'ExampleAppID',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    comments: {added: [{lang: 'en', value: 'Example comment'}]},
    newVisibility: {visibility: 'PUBLIC'},
    properties: {
      added: [
        {
          langLiteralValue: {lang: 'en', value: 'Example Property Value'},
          literalValue: {},
          stringLiteralValue: {},
          uriValue: {}
        }
      ]
    }
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https:///qapi/twins/did%3Aiotics%3AiotVNNQJc4bVQjDuMDThZqW7cd664VQGUvCT")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Patch.new(url)
request["Accept"] = 'application/json'
request["Iotics-ClientRef"] = 'ExampleRef'
request["Iotics-ClientAppId"] = 'ExampleAppID'
request["Content-Type"] = 'application/json'
request.body = "{\"comments\":{\"added\":[{\"lang\":\"en\",\"value\":\"Example comment\"}]},\"newVisibility\":{\"visibility\":\"PUBLIC\"},\"properties\":{\"added\":[{\"langLiteralValue\":{\"lang\":\"en\",\"value\":\"Example Property Value\"},\"literalValue\":{},\"stringLiteralValue\":{},\"uriValue\":{}}]}}"

response = http.request(request)
puts response.read_body

const options = {
  method: 'PATCH',
  headers: {
    Accept: 'application/json',
    'Iotics-ClientRef': 'ExampleRef',
    'Iotics-ClientAppId': 'ExampleAppID',
    'Content-Type': 'application/json'
  },
  body: '{"comments":{"added":[{"lang":"en","value":"Example comment"}]},"newVisibility":{"visibility":"PUBLIC"},"properties":{"added":[{"langLiteralValue":{"lang":"en","value":"Example Property Value"},"literalValue":{},"stringLiteralValue":{},"uriValue":{}}]}}'
};

fetch('https:///qapi/twins/did%3Aiotics%3AiotVNNQJc4bVQjDuMDThZqW7cd664VQGUvCT', options)
  .then(response => console.log(response))
  .catch(err => console.error(err));

import requests

url = "https:///qapi/twins/did%3Aiotics%3AiotVNNQJc4bVQjDuMDThZqW7cd664VQGUvCT"

payload = {
    "comments": {"added": [
            {
                "lang": "en",
                "value": "Example comment"
            }
        ]},
    "newVisibility": {"visibility": "PUBLIC"},
    "properties": {"added": [
            {
                "langLiteralValue": {
                    "lang": "en",
                    "value": "Example Property Value"
                },
                "literalValue": {},
                "stringLiteralValue": {},
                "uriValue": {}
            }
        ]}
}
headers = {
    "Accept": "application/json",
    "Iotics-ClientRef": "ExampleRef",
    "Iotics-ClientAppId": "ExampleAppID",
    "Content-Type": "application/json"
}

response = requests.request("PATCH", url, json=payload, headers=headers)

print(response.text)

In this example we've added a new comment, a new property and set the Twin's visibility to PUBLIC.

Setting up a Digital Twin

Set your headers

The Post request

Body parameters

Viewing your Twin

Path parameters

Query parameters

Populating your Twin

Path parameters

Body parameters

🚧
Note

Comments

Labels

Location

newVisibility

Properties

🚧
Note

Tags

Examples

Example POST request

Example GET request

Example PATCH request

Set your headers

The Post request

Body parameters

Viewing your Twin

Path parameters

Query parameters

Populating your Twin

Path parameters

Body parameters

🚧Note

Comments

Labels

Location

newVisibility

Properties

🚧Note

Tags

Examples

Example POST request

Example GET request

Example PATCH request

🚧
Note

🚧
Note