Changes to labels, comments and tags - effective 27 January 2022

The refactoring of the IOTICS ontology introduced a set of breaking changes in the IOTICS API. This documentation's purpose is to help the users with the code migration.

📘
Note:
All existing twins will be automatically migrated on 27 January 2022.
However, you need to update your code when using connectors and applications.

This page covers the changes for 3 types of users:

Overview

Features

Feeds have properties. Impacts:
- Update feed request
- Upsert twin request
- Describe feed response
- Search response (FULL type)

Breaking changes

Labels, comments, and tags have been removed. Impacts:
- Update twin/feed request
- Describe twin/feed request/response
- Upsert twin request
- Search response (FULL/LOCATED type)
Create feed: storeLast is removed from request / alreadyCreated is removed from response
Create/Delete/Update twin responses only includes twin ID
Nested describe twin/feed response objects have been renamed

Web API code migration based on iotic.web.rest.client

This section highlights how to migrate the client code using iotic.web.rest.client package in Python (version >= 2.0.109).

Set twin/feed labels and comments

Twin/feed labels and comments have been downgraded from special to generic properties in order to streamline and simplify the API's semantic search capabilities.

The special twin/feed labels and comments used to be indexed for the Search By Text purpose. That means they were used to match a twin when the user was running a search by text.

Following this new API change, any properties of type label and comment are indexed for search by text.

How to migrate a twin/feed label

Replace any occurrences of:

english_label = LangLiteral(value='a label', lang='en')
[...]

labels=LabelUpdate(added=[english_label]),
# OR
labels=[english_label],

with:

english_label = LangLiteral(value='a label', lang='en')
[...]

properties=PropertyUpdate(added=[
        ModelProperty(key='http://www.w3.org/2000/01/rdf-schema#label', 
        lang_literal_value=english_label),
    ]),
# OR
properties=[
        ModelProperty(key='http://www.w3.org/2000/01/rdf-schema#label', 
        lang_literal_value=english_label),
    ],

The same applies for comments using 'http://www.w3.org/2000/01/rdf-schema#comment'

Code update examples

Twin update

Code example before changes:

from iotic.web.rest.client.qapi import ApiClient, CommentUpdate, LabelUpdate, LangLiteral, PropertyUpdate, TwinApi, \
    UpdateTwinRequestPayload

rest_api_client = TwinApi(api_client=ApiClient(...))
[...]

english_label = LangLiteral(value='a label', lang='en')
english_comment = LangLiteral(value='a comment', lang='en')

payload = UpdateTwinRequestPayload(
    labels=LabelUpdate(added=[english_label]),
    comments=CommentUpdate(added=[english_comment]),
    properties=PropertyUpdate(added=[...]),
)
rest_api_client.update_twin(twin_id=twin_id,
                            iotics_client_app_id='my app id',
                            body=payload)

Code example after changes:

from iotic.web.rest.client.qapi import ApiClient, LangLiteral, ModelProperty, PropertyUpdate, TwinApi, \
    UpdateTwinRequestPayload

rest_api_client = TwinApi(api_client=ApiClient(...))
[...]

english_label = LangLiteral(value='a label', lang='en')
english_comment = LangLiteral(value='a comment', lang='en')

payload = UpdateTwinRequestPayload(
    properties=PropertyUpdate(added=[
        ModelProperty(key='http://www.w3.org/2000/01/rdf-schema#label', lang_literal_value=english_label),
        ModelProperty(key='http://www.w3.org/2000/01/rdf-schema#comment', lang_literal_value=english_comment),
    ]),
)
rest_api_client.update_twin(twin_id=twin_id,
                            iotics_client_app_id='my app id',
                            body=payload)

Feed update

Code example before changes:

from iotic.web.rest.client.qapi import ApiClient, CommentUpdate, FeedApi, LabelUpdate, LangLiteral, \
    UpdateFeedRequestPayload

rest_api_client = FeedApi(api_client=ApiClient(...))
[...]

english_label = LangLiteral(value='a label', lang='en')
english_comment = LangLiteral(value='a comment', lang='en')

payload = UpdateFeedRequestPayload(
    labels=LabelUpdate(added=[english_label]),
    comments=CommentUpdate(added=[english_comment]),
    [...]
)
rest_api_client.update_feed(twin_id=twin_id,
                            feed_id=feed_id,
                            iotics_client_app_id='my app id',
                            body=payload)

Code example after changes:

from iotic.web.rest.client.qapi import ApiClient, FeedApi, LangLiteral, ModelProperty, PropertyUpdate, \
    UpdateFeedRequestPayload

rest_api_client = FeedApi(api_client=ApiClient(...))
[...]

english_label = LangLiteral(value='a label', lang='en')
english_comment = LangLiteral(value='a comment', lang='en')

payload = UpdateFeedRequestPayload(
    properties=PropertyUpdate(added=[
        ModelProperty(key='http://www.w3.org/2000/01/rdf-schema#label', lang_literal_value=english_label),
        ModelProperty(key='http://www.w3.org/2000/01/rdf-schema#comment', lang_literal_value=english_comment),
    ]),
)
rest_api_client.update_feed(twin_id=twin_id,
                            feed_id=feed_id,
                            iotics_client_app_id='my app id',
                            body=payload)

Twin/feed upsert

Code example before changes:

from iotic.web.rest.client.qapi import ApiClient, LangLiteral, TwinApi, UpsertFeedWithMeta, UpsertTwinRequestPayload

rest_api_client = TwinApi(api_client=ApiClient(...))

twin_english_label = LangLiteral(value='a twin label', lang='en')
twin_english_comment = LangLiteral(value='a twin comment', lang='en')

feed_english_label = LangLiteral(value='a feed label', lang='en')
feed_english_comment = LangLiteral(value='a feed comment', lang='en')

payload = UpsertTwinRequestPayload(
    twin_id=twin_id,
    labels=[twin_english_label],
    comments=[twin_english_comment],
    properties=[...],
    feeds=[
        UpsertFeedWithMeta(id=feed_id,
                           labels=[feed_english_label],
                           comments=[feed_english_comment],
                           [...],
                           )
    ],
)
rest_api_client.upsert_twin(iotics_client_app_id='my app id',
                            body=payload)

Code example after changes:

from iotic.web.rest.client.qapi import ApiClient, LangLiteral, ModelProperty, TwinApi, UpsertFeedWithMeta, \
    UpsertTwinRequestPayload

rest_api_client = TwinApi(api_client=ApiClient(...))

twin_english_label = LangLiteral(value='a twin label', lang='en')
twin_english_comment = LangLiteral(value='a twin comment', lang='en')

feed_english_label = LangLiteral(value='a feed label', lang='en')
feed_english_comment = LangLiteral(value='a feed comment', lang='en')

payload = UpsertTwinRequestPayload(
    twin_id=twin_id,
    properties=[
        ModelProperty(key='http://www.w3.org/2000/01/rdf-schema#label', lang_literal_value=twin_english_label),
        ModelProperty(key='http://www.w3.org/2000/01/rdf-schema#comment', lang_literal_value=twin_english_comment),
    ],
    feeds=[
        UpsertFeedWithMeta(id=feed_id,
                           properties=[
                               ModelProperty(key='http://www.w3.org/2000/01/rdf-schema#label',
                                             lang_literal_value=feed_english_label),
                               ModelProperty(key='http://www.w3.org/2000/01/rdf-schema#comment',
                                             lang_literal_value=feed_english_comment),
                           ],
                           [...],
                           )
    ],
)
rest_api_client.upsert_twin(iotics_client_app_id='my app id',
                            body=payload)

Get properties (get labels/comments/any property)

Before the changes, twin/feed labels and comments were returned in separate special fields. Now they are listed alongside the other properties.

The describe twin/feed and the search language filtering have also been removed. The language is present in the label/comment/… properties.

Payload update example

Twin describe

Response payload example before changes:

{
  'twin': {
    'id': {'value': 'did:iotics:iotAoex4EtGDrXdn5zibQDMCsGu29geziCnr'},
    'visibility': 'PUBLIC'
  }
  'result': {
    'comments': [
        {'lang': 'en', 'value': 'a comment for my twin'},
        {'lang': 'fr', 'value': 'un commentaire pour ma twin'}
    ],
    'labels': [
        {'lang': 'en', 'value': 'a label for my twin'},
        {'lang': 'fr', 'value': 'un label pour ma twin'}
    ],
    'properties': [
        {
          'key': 'http://data.iotics.com/public#hostAllowList',
          'uri_value': {'value': 'http://data.iotics.com/public#noHost'}
        }
    ],
 [...]                 
}

Response payload example after changes:

{
  'twin': {
    'id': {'value': 'did:iotics:iotAoex4EtGDrXdn5zibQDMCsGu29geziCnr'},
    'visibility': 'PUBLIC'
  }
  'result': {
    'properties': [
        {
          'key': 'http://data.iotics.com/public#hostAllowList',
          'uri_value': {'value': 'http://data.iotics.com/public#noHost'}
        },
        {
          'key': 'http://www.w3.org/2000/01/rdf-schema#comment',
          'lang_literal_value': {'lang': 'en', value': 'a comment for my twin'}
        },
        {
          'key': 'http://www.w3.org/2000/01/rdf-schema#comment',
          'lang_literal_value': {'lang': 'fr', value': 'un commentaire pour ma twin'}
        },
        {
          'key': 'http://www.w3.org/2000/01/rdf-schema#label',
          'lang_literal_value': {'lang': 'en', 'value': 'a label for my twin'},
        },
        {
          'key': 'http://www.w3.org/2000/01/rdf-schema#label',
          'lang_literal_value': {'lang': 'fr', 'value': 'un label pour ma twin'},
        },
      ],
 [...]                 
}

Feed describe

Response payload example before changes:

{
  'feed': {'id': {'value': 'feed 1'},
          'twin_id': {'value': 'did:iotics:iotAoex4EtGDrXdn5zibQDMCsGu29geziCnr'}},
  'result': {
    'comments': [
        {'lang': 'en', 'value': 'a comment for my feed'},
        {'lang': 'fr', 'value': 'un commentaire pour mon feed'}
    ],
    'labels': [
        {'lang': 'en', 'value': 'a label for my feed'},
        {'lang': 'fr', 'value': 'un label pour mon feed'}
    ],
    'store_last': True,
    [...]
}

Response payload example after changes:

{
  'feed': {'id': {'value': 'feed 1'},
          'twin_id': {'value': 'did:iotics:iotAoex4EtGDrXdn5zibQDMCsGu29geziCnr'}},
  'result': {
    'properties': [
          {
          'key': 'http://www.w3.org/2000/01/rdf-schema#comment',
          'lang_literal_value': {'lang': 'en', value': 'a comment for my feed'}
        },
        {
          'key': 'http://www.w3.org/2000/01/rdf-schema#comment',
          'lang_literal_value': {'lang': 'fr', value': 'un commentaire pour mon feed'}
        },
        {
          'key': 'http://www.w3.org/2000/01/rdf-schema#label',
          'lang_literal_value': {'lang': 'en', 'value': 'a label for my feed'},
        },
        {
          'key': 'http://www.w3.org/2000/01/rdf-schema#label',
          'lang_literal_value': {'lang': 'fr', 'value': 'un label pour mon feed'},
        },
    ],
    'store_last': True,
    [...]
}

Full search response

Response payload example before changes:

{
  'headers': {[...]},
  'payload': {
    'response_type': 'FULL',
    'twins': [
      {
        'id': {'value': 'did:iotics:iotSRG2F95t7M7Wuq1HtkTgHv7umKK7xaDNZ'},
        'label': 'a twin label',
        'properties': [
          {
            'key': 'http://data.iotics.com/public#hostAllowList',
            'uri_value': {'value': 'http://data.iotics.com/public#allHosts'}
          }
        ],
        'feeds': [
          {
            'feed': {'id': {'value': 'feed 1'},
                     'twin_id': {'value': 'did:iotics:iotSRG2F95t7M7Wuq1HtkTgHv7umKK7xaDNZ'}},
            'label': 'a feed label',
            'store_last': False,
          },
        ],
     [...]
}

Response payload example after changes:

{
  'headers': {[...]},
  'payload': {
    'response_type': 'FULL',
    'twins': [
      {
        'id': {'value': 'did:iotics:iotSRG2F95t7M7Wuq1HtkTgHv7umKK7xaDNZ'},
        'properties': [
          {
            'key': 'http://data.iotics.com/public#hostAllowList',
            'uri_value': {'value': 'http://data.iotics.com/public#allHosts'}
          },
          {
            'key': 'http://www.w3.org/2000/01/rdf-schema#label',
            'lang_literal_value': {'value': 'a twin label', lang: 'en'}
          },
        ],
        'feeds': [
          {
            'feed': {'id': {'value': 'feed 1'},
                     'twin_id': {'value': 'did:iotics:iotSRG2F95t7M7Wuq1HtkTgHv7umKK7xaDNZ'}},
            'properties': [
              {
                'key': 'http://www.w3.org/2000/01/rdf-schema#label',
                'lang_literal_value': {'value': 'a feed label', lang: 'en'}
              },
            ],
            'store_last': False,
          },
        ],
     [...]
}

Remove tags

Tags have been removed and therefore can not be set or read any more. The list of affected objects is:

iotic.web.rest.client.qapi.models.tags change:
- Tags has been removed
DescribeTwinResponse object structure change:
- response.payload.result.tags has been removed
DescribeFeedResponse object structure change:
- response.payload.result.tags has been removed
SearchResponse object structure change:
- response.payload.twins[].tags has been removed
UpdateTwinRequest object structure change:
- request.payload.tags has been removed
UpdateFeedRequest object structure change:
- request.payload.tags has been removed

Remove storeLast flag from create feed request

It is no longer possible to set the storeLast flag while creating a feed using create feed. This can still be done using update feed or upsert twin.

Code update example

Code example before changes:

from iotic.web.rest.client.qapi import ApiClient, CreateFeedRequestPayload, FeedApi, FeedID

rest_api_client = FeedApi(api_client=ApiClient(...))
[...]

payload = CreateFeedRequestPayload(feed_id=FeedID(value=feed_id),
                                   store_last=True)
rest_api_client.create_feed(twin_id=twin_id,
                            iotics_client_app_id='my app id',
                            body=payload)

Code example after changes:

from iotic.web.rest.client.qapi import ApiClient, CreateFeedRequestPayload, FeedApi, FeedID

rest_api_client = FeedApi(api_client=ApiClient(...))
[...]

payload = CreateFeedRequestPayload(feed_id=FeedID(value=feed_id))
rest_api_client.create_feed(twin_id=twin_id,
                            iotics_client_app_id='my app id',
                            body=payload)

payload = UpdateFeedRequestPayload(store_last=True)
rest_api_client.update_feed(twin_id=twin_id,
                            feed_id=feed_id,
                            iotics_client_app_id='my app id',
                            body=payload)

Create feed response

The CreateFeedResponse no longer contains information to know if the feed was already created. The way to know if a feed exists is to describe the twin or to attempt to describe the feed. If it does not exist a 404 NOT FOUND will be returned.

CreateFeedResponse object structure change:
- response.payload.already_created has been removed

Create/Update/Delete twin Response

The Create/Update/Delete requests structure has changed. Now only the twin identifier is returned.

CreateTwinResponse object structure changes:
- response.payload.already_created has been removed
- response.payload.twin has been removed
- response.payload.twin_id has been added
UpdateTwinResponse object structure changes:
- response.payload.twin has been removed
- response.payload.twin_id has been added
DeleteTwinResponse object structure changes:
- response.payload.twin has been removed
- response.payload.twin_id has been added

The way to know if a twin exists is to attempt to describe it. If it does not exist a 404 NOT FOUND will be returned.

response.payload.twin to response.payload.twin_id code change (applicable to all the response mentioned above)

Code example before changes:

response = api.delete_twin(twin_id=twin_id, iotics_client_app_id='my app id')
print(response.payload.twin.id.value)

Code example after changes:

response = api.delete_twin(twin_id=twin_id, iotics_client_app_id='my app id')
print(response.payload.twin_id.value)

Web API code migration (raw usage)

This section highlights how to migrate the Python client code using the IOTICS Web API
(version >= 2.0.109).

Twin/feed labels and comments have been downgraded from special to generic properties in order to streamline and simplify the API's semantic search capabilities.

The special twin/feed labels and comments used to be indexed for the Search By Text purpose. That means they were used to match a twin when the user was running a search by text.

Following this new API change, any properties of type label and comment are indexed for search by text.

How to migrate a twin/feed label

Replace any occurrences of:

english_label = {'value': 'a label', 'lang': 'en'}
[...]
payload = {
  'labels': {'added': [english_label]}
}
# OR
payload = {
  'labels': [english_label]
}

with:

english_label = {'value': 'a label', 'lang': 'en'}
[...]
payload = {
  'properties': {
    'added': [
        {
          'key': 'http://www.w3.org/2000/01/rdf-schema#label', 
          'langLiteralValue': english_label
        }
      ]
    }
}
# OR
payload = {
  'properties': [
    {
      'key': 'http://www.w3.org/2000/01/rdf-schema#label', 
      'langLiteralValue': english_label
    }
  ]
}

Same for comments using 'http://www.w3.org/2000/01/rdf-schema#comment'

Code update example:

Twin/feed update

Code example before changes:

import requests
[...]

english_label = {'value': 'a label', 'lang': 'en'}
english_comment = {'value': 'a comment', 'lang': 'en'}
payload = {
  'labels': {'added': [english_label]},
  'comments': {'added': [english_comment]},
  [...]
}
requests.patch([...], json=payload)

Code example after changes:

import requests
[...]

english_label = {'value': 'a label', 'lang': 'en'}
english_comment = {'value': 'a comment', 'lang': 'en'}
payload = {
  'properties': {
    'added': [
        {
          'key': 'http://www.w3.org/2000/01/rdf-schema#label', 
          'langLiteralValue': english_label
        },
        {
          'key': 'http://www.w3.org/2000/01/rdf-schema#comment', 
          'langLiteralValue': english_comment
        }
      ]
    }
}
requests.patch([...], json=payload)

Twin/feed upsert

Code example before changes:

import requests
[...]

twin_english_label = {'value': 'a twin label', 'lang': 'en'}
twin_english_comment = {'value': 'a twin comment', 'lang': 'en'}

feed_english_label = {'value': 'a feed label', 'lang': 'en'}
feed_english_comment = {'value': 'a feed comment', 'lang': 'en'}
payload = {
  'twin_id': twin_id,
  'labels': {'added': [twin_english_label]},
  'comments': {'added': [twin_english_comment]},
  'properties': [],
  'feeds': [
    {
      'id': feed_id,
      'labels': {'added': [feed_english_label]},
      'comments': {'added': [feed_english_comment]},
      [...]      
    }
  ]
}

requests.put([...], json=payload)

Code example after changes:

import requests
[...]

twin_english_label = {'value': 'a twin label', 'lang': 'en'}
twin_english_comment = {'value': 'a twin comment', 'lang': 'en'}

feed_english_label = {'value': 'a feed label', 'lang': 'en'}
feed_english_comment = {'value': 'a feed comment', 'lang': 'en'}
payload = {
  'twin_id': twin_id,
  'properties': [
    {
      'key': 'http://www.w3.org/2000/01/rdf-schema#label', 
      'langLiteralValue': twin_english_label
    },
    {
      'key': 'http://www.w3.org/2000/01/rdf-schema#comment', 
      'langLiteralValue': twin_english_comment
    },
  ],
  'feeds': [
    {
      'id': feed_id,
      'properties': [
        {
          'key': 'http://www.w3.org/2000/01/rdf-schema#label', 
          'langLiteralValue': feed_english_label
        },
        {
          'key': 'http://www.w3.org/2000/01/rdf-schema#comment', 
          'langLiteralValue': feed_english_comment
        },
      ],
      [...]      
    }
  ]
}

requests.put([...], json=payload)

Get properties (get labels/comments/any property)

Before changes, twin/feed labels and comments were returned in special fields. Now they are returned alongside other properties.

The Describe twin/feed and the search language filtering have been removed. Now the language is present in the label/comment/… properties.

Payload update example

Twin describe

Response payload example before changes:

{
  'twin': {
    'id': {'value': 'did:iotics:iotAoex4EtGDrXdn5zibQDMCsGu29geziCnr'},
    'visibility': 'PUBLIC'
  }
  'result': {
    'comments': [
        {'lang': 'en', 'value': 'a comment for my twin'},
        {'lang': 'fr', 'value': 'un commentaire pour ma twin'}
    ],
    'labels': [
        {'lang': 'en', 'value': 'a label for my twin'},
        {'lang': 'fr', 'value': 'un label pour ma twin'}
    ],
    'properties': [
        {
          'key': 'http://data.iotics.com/public#hostAllowList',
          'uriValue': {'value': 'http://data.iotics.com/public#noHost'}
        }
    ],
 [...]                 
}

Response payload example after changes:

{
  'twin': {
    'id': {'value': 'did:iotics:iotAoex4EtGDrXdn5zibQDMCsGu29geziCnr'},
    'visibility': 'PUBLIC'
  }
  'result': {
    'properties': [
        {
          'key': 'http://data.iotics.com/public#hostAllowList',
          'uriValue': {'value': 'http://data.iotics.com/public#noHost'}
        },
        {
          'key': 'http://www.w3.org/2000/01/rdf-schema#comment',
          'langLiteralValue': {'lang': 'en', value': 'a comment for my twin'}
        },
        {
          'key': 'http://www.w3.org/2000/01/rdf-schema#comment',
          'langLiteralValue': {'lang': 'fr', value': 'un commentaire pour ma twin'}
        },
        {
          'key': 'http://www.w3.org/2000/01/rdf-schema#label',
          'langLiteralValue': {'lang': 'en', 'value': 'a label for my twin'},
        },
        {
          'key': 'http://www.w3.org/2000/01/rdf-schema#label',
          'langLiteralValue': {'lang': 'fr', 'value': 'un label pour ma twin'},
        },
      ],
 [...]                 
}

Feed describe

Response payload example before changes:

{
  'feed': {'id': {'value': 'feed 1'},
          'twinId': {'value': 'did:iotics:iotAoex4EtGDrXdn5zibQDMCsGu29geziCnr'}},
  'result': {
    'comments': [
        {'lang': 'en', 'value': 'a comment for my feed'},
        {'lang': 'fr', 'value': 'un commentaire pour mon feed'}
    ],
    'labels': [
        {'lang': 'en', 'value': 'a label for my feed'},
        {'lang': 'fr', 'value': 'un label pour mon feed'}
    ],
    'storeLast': True,
    [...]
}

Response payload example after changes:

{
  'feed': {'id': {'value': 'feed 1'},
          'twinId': {'value': 'did:iotics:iotAoex4EtGDrXdn5zibQDMCsGu29geziCnr'}},
  'result': {
    'properties': [
          {
          'key': 'http://www.w3.org/2000/01/rdf-schema#comment',
          'langLiteralValue': {'lang': 'en', value': 'a comment for my feed'}
        },
        {
          'key': 'http://www.w3.org/2000/01/rdf-schema#comment',
          'langLiteralValue': {'lang': 'fr', value': 'un commentaire pour mon feed'}
        },
        {
          'key': 'http://www.w3.org/2000/01/rdf-schema#label',
          'langLiteralValue': {'lang': 'en', 'value': 'a label for my feed'},
        },
        {
          'key': 'http://www.w3.org/2000/01/rdf-schema#label',
          'langLiteralValue': {'lang': 'fr', 'value': 'un label pour mon feed'},
        },
    ],
    'storeLast': True,
    [...]
}

Full search

Response payload example before changes:

{
  'headers': {[...]},
  'payload': {
    'responseType': 'FULL',
    'twins': [
      {
        'id': {'value': 'did:iotics:iotSRG2F95t7M7Wuq1HtkTgHv7umKK7xaDNZ'},
        'label': 'a twin label',
        'properties': [
          {
            'key': 'http://data.iotics.com/public#hostAllowList',
            'uriValue': {'value': 'http://data.iotics.com/public#allHosts'}
          }
        ],
        'feeds': [
          {
            'feed': {'id': {'value': 'feed 1'},
                     'twinId': {'value': 'did:iotics:iotSRG2F95t7M7Wuq1HtkTgHv7umKK7xaDNZ'}},
            'label': 'a feed label',
            'storeLast': False,
          },
        ],
     [...]
}

Response payload example after changes:

{
  'headers': {[...]},
  'payload': {
    'responseType': 'FULL',
    'twins': [
      {
        'id': {'value': 'did:iotics:iotSRG2F95t7M7Wuq1HtkTgHv7umKK7xaDNZ'},
        'properties': [
          {
            'key': 'http://data.iotics.com/public#hostAllowList',
            'uriValue': {'value': 'http://data.iotics.com/public#allHosts'}
          },
          {
            'key': 'http://www.w3.org/2000/01/rdf-schema#label',
            'langLiteralValue': {'value': 'a twin label', lang: 'en'}
          },
        ],
        'feeds': [
          {
            'feed': {'id': {'value': 'feed 1'},
                     'twinId': {'value': 'did:iotics:iotSRG2F95t7M7Wuq1HtkTgHv7umKK7xaDNZ'}},
            'properties': [
              {
                'key': 'http://www.w3.org/2000/01/rdf-schema#label',
                'langLiteralValue': {'value': 'a feed label', lang: 'en'}
              },
            ],
            'storeLast': False,
          },
        ],
     [...]
}

Remove tags

Tags have been removed and they can not be set or read any more. The list of affected objects is:

DescribeTwinResponse object structure change:
- response.payload.result.tags has been removed
DescribeFeedResponse object structure change:
- response.payload.result.tags has been removed
SearchResponse object structure change:
- response.payload.twins[].tags has been removed
UpdateTwinRequest object structure change:
- request.payload.tags has been removed
UpdateFeedRequest object structure change:
- request.payload.tags has been removed

Remove storeLast flag from create feed request

It is no longer possible to set the storeLast flag while creating a feed using create feed. This can still be done using update feed or upsert twin.

Code update example

Code example before changes:

import requests
[...]

payload = {"feedId": feed_id,
           "storeLast": True}
requests.post([...], json=payload)

Code example after changes:

fimport requests
[...]

payload = {"feedId": feed_id}
requests.post([...], json=payload)

payload = {"storeLast": True}
requests.patch([...], json=payload)

Create feed response

The CreateFeedResponse no longer contains information to know if the feed was already created. The way to know if a feed exists is to describe the twin or to attempt to describe the feed. If it does not exist a 404 NOT FOUND will be returned.

CreateFeedResponse object structure change
- response.payload.alreadyCreated has been removed

Create/Update/Delete twin response

The Create/Update/Delete requests structure has changed. Now only the twin identifier is returned.

CreateTwinResponse object structure changes:
- response.payload.alreadyCreated has been removed
- response.payload.twin has been removed
- response.payload.twinId has been added
UpdateTwinResponse object structure changes:
- response.payload.twin has been removed
- response.payload.twinId has been added
DeleteTwinResponse object structure changes:
- response.payload.twin has been removed
- response.payload.twinId has been added

The way to know if a twin exists is to attempt to describe it. If it does not exist a 404 NOT FOUND will be returned.

response.payload.twin to response.payload.twinId code change (applicable to all the response mentioned above)

Code example before changes:

print(response_payload['twin']['id']['value'])

Code example after changes:

print(response_payload['twinId']['value'])

Iotics-host-lib code migration

This section highlights how to migrate the Python client code using iotics-host-lib.

🚧
Host Library v7.0
You need to install the new version of Host Library for the updates to work.

Set twin/feed labels and comments

Twin/feed labels and comments have been downgraded from special to generic properties in order to streamline and simplify the API's semantic search capabilities.

The special twin/feed labels and comments used to be indexed for the Search By Text purpose. That means they were used to match a twin when the user was running a search by text.

Following this new API change, any properties of type label and comment are indexed for search by text.

How to migrate a twin/feed label

Replace any occurrences of:

english_label = LangLiteral(value='a label', lang='en')
[...]

labels=LabelUpdate(added=[english_label]),
# OR
labels=[english_label],

with:

english_label = LangLiteral(value='a label', lang='en')
[...]

properties=PropertyUpdate(added=[
        ModelProperty(key='http://www.w3.org/2000/01/rdf-schema#label', 
        lang_literal_value=english_label),
    ]),
# OR
properties=[
        ModelProperty(key='http://www.w3.org/2000/01/rdf-schema#label', 
        lang_literal_value=english_label),
    ],

The same applies for comments using 'http://www.w3.org/2000/01/rdf-schema#comment'

Code update example:

Twin update

Code example before changes:

from iotic.web.rest.client.qapi import LangLiteral, GeoLocation, GeoLocationUpdate
[...]

twin_api = qapi_factory.get_twin_api()
label = 'Random awesome twin'
description = 'Awesome twin for random data'
london_location = GeoLocationUpdate(location=GeoLocation(lat=51.507359, lon=-0.136439))
twin_api.update_twin(
    twin_id,
    add_tags=['random', 'awesome'],
    add_labels=[LangLiteral(value=label, lang='en')],
    add_comments=[LangLiteral(value=description, lang='en')],
    location=london_location,
)

Code example after changes:

from iotic.web.rest.client.qapi import LangLiteral, GeoLocation, GeoLocationUpdate, ModelProperty

[...]

twin_api = qapi_factory.get_twin_api()

english_label = ModelProperty(key='http://www.w3.org/2000/01/rdf-schema#label',
                              lang_literal_value=LangLiteral(lang='en', value='Random awesome twin'))

english_comment = ModelProperty(key='http://www.w3.org/2000/01/rdf-schema#comment',
                                lang_literal_value=LangLiteral(lang='en', value='Awesome twin for random data'))

london_location = GeoLocationUpdate(location=GeoLocation(lat=51.507359, lon=-0.136439))
twin_api.update_twin(
    twin_id,
    add_props=[english_label, english_comment],
    location=london_location,
)

Feed update

Code example before changes:

from iotic.web.rest.client.qapi import LangLiteral, Value
[...]

feed_api = qapi_factory.get_feed_api()

label = 'Random temperature feed'
description = f'Awesome feed generating a temperature in Celsius each {update_frequency_seconds} seconds'
feed_api.update_feed(
    twin_id, feed_name,
    add_labels=[LangLiteral(value=label, lang='en')],
    add_comments=[LangLiteral(value=description, lang='en')],
    [...]
)

Code example after changes:

from iotic.web.rest.client.qapi import LangLiteral, ModelProperty

[...]
feed_api = qapi_factory.get_feed_api()

english_label = ModelProperty(key='http://www.w3.org/2000/01/rdf-schema#label',
                              lang_literal_value=LangLiteral(lang='en', value='Random temperature feed'))
english_comment = ModelProperty(key='http://www.w3.org/2000/01/rdf-schema#comment',
                                lang_literal_value=LangLiteral(lang='en',
                                                               value=f'Awesome feed generating a temperature in '
                                                                     f'Celsius each {update_frequency_seconds} seconds'))
feed_api.update_feed(
    twin_id, feed_name,
    add_props=[english_label, english_comment],
    [...]
)

Get Properties (get labels/comments/any property)

Before changes, twin/feed labels and comments were returned in special fields. Now they are returned alongside other properties.

Payload update example

Twin describe

Response payload example before changes:

{
  'twin': {
    'id': {'value': 'did:iotics:iotAoex4EtGDrXdn5zibQDMCsGu29geziCnr'},
    'visibility': 'PUBLIC'
  }
  'result': {
    'comments': [
        {'lang': 'en', 'value': 'a comment for my twin'},
        {'lang': 'fr', 'value': 'un commentaire pour ma twin'}
    ],
    'labels': [
        {'lang': 'en', 'value': 'a label for my twin'},
        {'lang': 'fr', 'value': 'un label pour ma twin'}
    ],
    'properties': [
        {
          'key': 'http://data.iotics.com/public#hostAllowList',
          'uri_value': {'value': 'http://data.iotics.com/public#noHost'}
        }
    ],
 [...]                 
}

Response payload example after changes:

{
  'twin': {
    'id': {'value': 'did:iotics:iotAoex4EtGDrXdn5zibQDMCsGu29geziCnr'},
    'visibility': 'PUBLIC'
  }
  'result': {
    'properties': [
        {
          'key': 'http://data.iotics.com/public#hostAllowList',
          'uri_value': {'value': 'http://data.iotics.com/public#noHost'}
        },
        {
          'key': 'http://www.w3.org/2000/01/rdf-schema#comment',
          'lang_literal_value': {'lang': 'en', value': 'a comment for my twin'}
        },
        {
          'key': 'http://www.w3.org/2000/01/rdf-schema#comment',
          'lang_literal_value': {'lang': 'fr', value': 'un commentaire pour ma twin'}
        },
        {
          'key': 'http://www.w3.org/2000/01/rdf-schema#label',
          'lang_literal_value': {'lang': 'en', 'value': 'a label for my twin'},
        },
        {
          'key': 'http://www.w3.org/2000/01/rdf-schema#label',
          'lang_literal_value': {'lang': 'fr', 'value': 'un label pour ma twin'},
        },
      ],
 [...]                 
}

Feed describe

Response payload example before changes:

{
  'feed': {'id': {'value': 'feed 1'},
          'twin_id': {'value': 'did:iotics:iotAoex4EtGDrXdn5zibQDMCsGu29geziCnr'}},
  'result': {
    'comments': [
        {'lang': 'en', 'value': 'a comment for my feed'},
        {'lang': 'fr', 'value': 'un commentaire pour mon feed'}
    ],
    'labels': [
        {'lang': 'en', 'value': 'a label for my feed'},
        {'lang': 'fr', 'value': 'un label pour mon feed'}
    ],
    'store_last': True,
    [...]
}

Response payload example after changes:

{
  'feed': {'id': {'value': 'feed 1'},
          'twin_id': {'value': 'did:iotics:iotAoex4EtGDrXdn5zibQDMCsGu29geziCnr'}},
  'result': {
    'properties': [
          {
          'key': 'http://www.w3.org/2000/01/rdf-schema#comment',
          'lang_literal_value': {'lang': 'en', value': 'a comment for my feed'}
        },
        {
          'key': 'http://www.w3.org/2000/01/rdf-schema#comment',
          'lang_literal_value': {'lang': 'fr', value': 'un commentaire pour mon feed'}
        },
        {
          'key': 'http://www.w3.org/2000/01/rdf-schema#label',
          'lang_literal_value': {'lang': 'en', 'value': 'a label for my feed'},
        },
        {
          'key': 'http://www.w3.org/2000/01/rdf-schema#label',
          'lang_literal_value': {'lang': 'fr', 'value': 'un label pour mon feed'},
        },
    ],
    'store_last': True,
    [...]
}

Full search

Response payload example before changes:

{
  'headers': {[...]},
  'payload': {
    'response_type': 'FULL',
    'twins': [
      {
        'id': {'value': 'did:iotics:iotSRG2F95t7M7Wuq1HtkTgHv7umKK7xaDNZ'},
        'label': 'a twin label',
        'properties': [
          {
            'key': 'http://data.iotics.com/public#hostAllowList',
            'uri_value': {'value': 'http://data.iotics.com/public#allHosts'}
          }
        ],
        'feeds': [
          {
            'feed': {'id': {'value': 'feed 1'},
                     'twin_id': {'value': 'did:iotics:iotSRG2F95t7M7Wuq1HtkTgHv7umKK7xaDNZ'}},
            'label': 'a feed label',
            'store_last': False,
          },
        ],
     [...]
}

Response payload example after changes:

{
  'headers': {[...]},
  'payload': {
    'response_type': 'FULL',
    'twins': [
      {
        'id': {'value': 'did:iotics:iotSRG2F95t7M7Wuq1HtkTgHv7umKK7xaDNZ'},
        'properties': [
          {
            'key': 'http://data.iotics.com/public#hostAllowList',
            'uri_value': {'value': 'http://data.iotics.com/public#allHosts'}
          },
          {
            'key': 'http://www.w3.org/2000/01/rdf-schema#label',
            'lang_literal_value': {'value': 'a twin label', lang: 'en'}
          },
        ],
        'feeds': [
          {
            'feed': {'id': {'value': 'feed 1'},
                     'twin_id': {'value': 'did:iotics:iotSRG2F95t7M7Wuq1HtkTgHv7umKK7xaDNZ'}},
            'properties': [
              {
                'key': 'http://www.w3.org/2000/01/rdf-schema#label',
                'lang_literal_value': {'value': 'a feed label', lang: 'en'}
              },
            ],
            'store_last': False,
          },
        ],
     [...]
}

Remove tags

Tags have been removed, they can not be set or read any more.

List of affected objects:

iotic.web.rest.client.qapi.models.tags.Tags has been removed
DescribeTwinResponse object structure change:
- response.payload.result.tags has been removed
DescribeFeedResponse object structure change:
- response.payload.result.tags has been removed
SearchResponse object structure change:
- response.payload.twins[].tags has been removed
UpdateTwinRequest object structure change:
- request.payload.tags has been removed
UpdateFeedRequest object structure change:
- request.payload.tags has been removed

List of affected API entries:

TwinApi.describe_twin response does not include tags any more (see DescribeTwinResponse above)
TwinApi.update_twin parameters add_tags and del_tags have been removed
FeedApi.describe_twin response does not include tags any more (see DescribeFeedResponse above)
FeedApi.update_twin parameters add_tags and del_tags have been removed
SearchAPI.search_twins responses do not include tags any more (see SearchResponse above)

Create Feed response

CreateFeedResponse object (returned by FeedApi.create_feed) structure change:
- response.payload.already_created has been removed

Create/Update/Delete twin response

The Create/Update/Delete requests structure has changed. Now only the twin identifier is returned.

CreateTwinResponse object (returned by TwinApi.create_twin) structure changes:
- response.payload.already_created has been removed
- response.payload.twin has been removed
- response.payload.twin_id has been added
UpdateTwinResponse object (returned by TwinApi.update_twin) structure changes:
- response.payload.twin has been removed
- response.payload.twin_id has been added
DeleteTwinResponse object (returned by TwinApi.delete_twin) structure changes:
- response.payload.twin has been removed
- response.payload.twin_id has been added

The way to know if a twin exists is to attempt to describe it. If it does not exist a 404 NOT FOUND will be returned.

response.payload.twin to response.payload.twin_id code change (applicable to all the response mentioned above).

Code example before changes:

response = api.delete_twin(twin_id=twin_id, iotics_client_app_id='my app id')
print(response.payload.twin.id.value)

Code example after changes:

response = api.delete_twin(twin_id=twin_id, iotics_client_app_id='my app id')
print(response.payload.twin_id.value)

MetaResult Renaming

Two response nested objects have been renamed:

iotic.web.rest.client.qapi.TwinMetaResult object has been renamed to iotic.web.rest.client.qapi.DescribeTwinResponseMetaResult
iotic.web.rest.client.qapi.MetaResult object has been renamed to iotic.web.rest.client.qapi.DescribeFeedResponseMetaResult

Changes to labels, comments and tags - effective 27 January 2022

📘
Note:

Overview

Features

Breaking changes

Web API code migration based on iotic.web.rest.client

Set twin/feed labels and comments

How to migrate a twin/feed label

Code update examples

Get properties (get labels/comments/any property)

Payload update example

Remove tags

Remove storeLast flag from create feed request

Code update example

Create feed response

Create/Update/Delete twin Response

Web API code migration (raw usage)

How to migrate a twin/feed label

Code update example:

Get properties (get labels/comments/any property)

Payload update example

Remove tags

Remove storeLast flag from create feed request

Code update example

Create feed response

Create/Update/Delete twin response

Iotics-host-lib code migration

🚧
Host Library v7.0

Set twin/feed labels and comments

How to migrate a twin/feed label

Code update example:

Get Properties (get labels/comments/any property)

Payload update example

Remove tags

Create Feed response

Create/Update/Delete twin response

MetaResult Renaming

📘Note:

Overview

Features

Breaking changes

Web API code migration based on iotic.web.rest.client

Set twin/feed labels and comments

How to migrate a twin/feed label

Code update examples

Get properties (get labels/comments/any property)

Payload update example

Remove tags

Remove storeLast flag from create feed request

Code update example

Create feed response

Create/Update/Delete twin Response

Web API code migration (raw usage)

How to migrate a twin/feed label

Code update example:

Get properties (get labels/comments/any property)

Payload update example

Remove tags

Remove storeLast flag from create feed request

Code update example

Create feed response

Create/Update/Delete twin response

Iotics-host-lib code migration

🚧Host Library v7.0

Set twin/feed labels and comments

How to migrate a twin/feed label

Code update example:

Get Properties (get labels/comments/any property)

Payload update example

Remove tags

Create Feed response

Create/Update/Delete twin response

MetaResult Renaming

📘
Note:

🚧
Host Library v7.0