This article is to show how manipulating Avatars in use of Thing'in Restful API which can be found at Develop > Thing’in API reference is going on. As can be imagined, manipulating avatars involves four phases: POST, DELETE, GET, and PUT. At the first step related to POST, avatars need to be created in order to manipulate an internet of things; then avatars which have been created can be further managed, modified, or even deleted through the rest of functions.
Here an example in use of existing ontologies will be delivered associated with the site of Orange at Meylan mainly comprising seven buildings with two floors. First things first, if you're not familiar with the Semantic World or you want a little reminder, go check this article : The Semantic world in easy mode
First of all, the fundamental of an internet of things is built based on nodes and links. Through Thing’in platform, a node can be created merely or with links connecting to existing avatars. For example, while creating a node of the site Orange Meylan, either a single architecture or with links towards seven buildings is capable of being a definition. To be more practical and specific, procedures corresponding to phases will be elaborated as follows.
Owing that each internet created is related to a certain Namespace, DO NOT mess up the existing database. For example here “OrangeMeylan” is adopted as Namespace. Another necessity of creating avatars is payload. As mentioned before, three kinds of relationships containing are elaborated or demonstrated: 1) all avatars alone, 2) architecture Orange Meylan connecting to seven buildings, and vice-versa, 3) seven buildings relating to architecture Orange Meylan.
In all cases, some elements for creating an avatar are required, at least an identifier IRI.
The CLASS of an avatar is now not mandatory (but a no class avatar should be considered by default as thing).
Nevertheless the classes of the avatara are indexed in Thing'in, then it helps efficiently to retreive the avatars. Another way to rapidly retrieve avatars is to attach labels to them. In Thing'in, a label is linked to an avatar with an edge, then using graph traversal from a label, leads directly to the attached avatars.
{
"avatars": [
{
"_iri": "http://Orange.fr/Grenoble",
"_classes": ["http://elite.polito.it/ontologies/dogont.owl#Architectural"],
"name": "Orange S.A.",
"industry": "Telecommunications",
"address": "28 chemin Vieux Chêne, 38240 Meylan, FRANCE"
}
]
}
{
"_avatars": [
{
"_iri": "http://Orange.fr/Grenoble/BuildingA",
"_classes": ["http://elite.polito.it/ontologies/dogont.owl#Building"],
"name": "Bâtiment A"
}
]
}
Obviously, above example codes show nodes without connecting to each other. Note that there are seven buildings mentioned before, i.e., Building A, B, E, F, G, H, I.
After trying to create an avatar, the Response Code 201 means creation completed. However, it’s not relevant to a successful creation. While using Thing’in platform for manipulation and management, each thing has two UUID series, one created once only at the very beginning, within a line
"location": http://<server-api>/api/things/UUID"
at the Response Headers, which is important and necessary if updating or reading functions are needed, noted as unique UUID, and another one with the main purpose of making connections will be discussed at the next subsection, relative UUID.
One more interesting point is ontology. Finding or building the right ontology can be referred to this article : Thing'in Enabler. Note that ontologies used in all example codes in this section are most from W3C semantic sensor network incubator group.
Due to the fact that while building nodes with links to certain existing nodes, the creation precedence needs to be taken into account. In this case, nodes representing seven buildings are created a priori.
{
"data": "string",
"_avatars": [
{
"_iri": "http://Orange.fr/Grenoble/BuildingA",
"_classes": ["http://elite.polito.it/ontologies/dogont.owl#Building"],
"name": "Bâtiment A"
}
]
}
This part is the same as the previous case because the seven building nodes are built first as existing things for being connected later. As known before, after each creation of node, the corresponding UUID, unique UUID, at the Response Headers should be recorded and then pass down to the function GET to read the relative information. Please refer to the part "GET or to Read a Thing".
Note : the naming of the propety should respect the ontology concept (dataproperty) or a Thing'in label name (define as property).
To create a node with links, _outE is utilized for describing edges or relationships of connections. Relative UUID and corresponding ORI are also needed to be targeted. Note that in this case, Orange Meylan is always a source with values of edges connected towards the targets.
{
"data": "string",
"_avatars": [
{
"_iri": "http://Orange.fr/Grenoble",
"_classes": ["http://elite.polito.it/ontologies/dogont.owl#Architectural"],
"name": "Orange S.A.",
"industry": "Telecommunications",
"address": "28 chemin Vieux Chêne, 38240 Meylan, FRANCE",
"_outE": [
{
"_label": "ontologies_dogont_owl_contains",
"_targetIRI": "http://Orange.fr/Grenoble/BuildingA"
},
{
"_label": "ontologies_dogont_owl_contains",
"_targetIRI": "http://Orange.fr/Grenoble/BuildingB"
},
{
"_label": "ontologies_dogont_owl_contains",
"_targetIRI": "http://Orange.fr/Grenoble/BuildingE"
},
{
"_label": "ontologies_dogont_owl_contains",
"_targetIRI": "http://Orange.fr/Grenoble/BuildingF"
},
{
"_label": "ontologies_dogont_owl_contains",
"_targetIRI": "http://Orange.fr/Grenoble/BuildingG"
},
{
"_label": "ontologies_dogont_owl_contains",
"_targetIRI": "http://Orange.fr/Grenoble/BuildingH"
},
{
"_label": "ontologies_dogont_owl_contains",
"_targetIRI": "http://Orange.fr/Grenoble/BuildingI"
}
]
}
]
}
The third case is just the inverse case which is then be omitted here.
In order to get to read an avatar, the corresponding unique UUID is required. Taking example of the second case mentioned in the previous subsection, after creating the first node of buildings in Orange Meylan, Building A, complete information can be obtained while passing the unique UUID to this GET API function.
{
"total_items": 1,
"items": [
{
"_depth": 0,
"_uuid": "9a074188-c35a-4111-91b8-aa9cb4bc386b",
"data": "string",
"_avatars": [
{
"_depth": 0,
"_iri": "http://Orange.fr/Grenoble/BuildingA",
"name": "Bâtiment A",
"_last_updated": 1523436043159,
"_uuid": "a5fff4bf-ee65-40af-8261-2616892eb878",
"_classes": ["http://elite.polito.it/ontologies/dogont.owl#Building"]
}
]
}
],
"index": 0,
"size": 100
}
From the result shown above, the first _uuid stands the unique UUID of Building A, whereas the second _uuid represents the relative UUID. Relative UUIDs can also be checked while exploring the data from Explore > Explore Thing’in Database, while unique UUIDs cannot.
Next, the result of Orange Meylan architecture connecting to the seven buildings are shown as
{
"total_items": 8,
"items": [
{
"_depth": 1,
"_uuid": "8d8606ca-d52e-46f4-9c94-fcf0d075afbf",
"data": "string",
"_projections": [
{
"_depth": 1,
"_iri": "http://Orange.fr/Grenoble/BuildingI",
"name": "Bâtiment I",
"_last_updated": 1523439096390,
"_uuid": "0954d38d-bfed-4302-8a8b-44fe2191eb41",
"_classes": ["http://elite.polito.it/ontologies/dogont.owl#Building"]
}
]
},
{
"_depth": 1,
"_uuid": "831e2933-43a9-44d1-930b-b4f74a15d096",
"data": "string",
"_avatars": [
{
"_depth": 1,
"_iri": "http://Orange.fr/Grenoble/BuildingF",
"name": "Bâtiment F",
"_last_updated": 1523438940263,
"_uuid": "6d063d65-c11b-40c7-b004-c69b14776b9c",
"_classes": ["http://elite.polito.it/ontologies/dogont.owl#Building"]
}
]
},
{
"_depth": 1,
"_uuid": "551b2244-2952-4d58-8b23-e522299799b1",
"data": "string",
"_avatars": [
{
"_depth": 1,
"_iri": "http://Orange.fr/Grenoble/BuildingG",
"name": "Bâtiment G",
"_last_updated": 1523438986647,
"_uuid": "65c0a6d8-7500-4b3f-9d5e-da7f5e71f71a",
"_classes": ["http://elite.polito.it/ontologies/dogont.owl#Building"]
}
]
},
{
"_depth": 1,
"_uuid": "9a074188-c35a-4111-91b8-aa9cb4bc386b",
"data": "string",
"_avatars": [
{
"_depth": 1,
"_iri": "http://Orange.fr/Grenoble/BuildingA",
"name": "Bâtiment A",
"_last_updated": 1523436043159,
"_uuid": "a5fff4bf-ee65-40af-8261-2616892eb878",
"_classes": ["http://elite.polito.it/ontologies/dogont.owl#Building"]
}
]
},
{
"_depth": 0,
"_uuid": "fff70768-42b9-4882-a0f5-9cc3d0b1b326",
"data": "string",
"_avatars": [
{
"_depth": 0,
"_iri": "http://Orange.fr/Grenoble",
"name": "Orange S.A.",
"_last_updated": 1523439314455,
"_uuid": "76a5f516-4038-4322-8214-8475835ebfb0",
"_outE": [
{
"_label": "ontologies_dogont_owl_contains",
"_targetUUID": "0954d38d-bfed-4302-8a8b-44fe2191eb41",
"_targetIRI": "http://Orange.fr/Grenoble/BuildingI"
},
{
"_label": "ontologies_dogont_owl_contains",
"_targetUUID": "74355204-b8c9-4bc3-a889-f7c606a945c7",
"_targetIRI": "http://Orange.fr/Grenoble/BuildingH"
},
{
"_label": "ontologies_dogont_owl_contains",
"_targetUUID": "65c0a6d8-7500-4b3f-9d5e-da7f5e71f71a",
"_targetIRI": "http://Orange.fr/Grenoble/BuildingG"
},
{
"_label": "ontologies_dogont_owl_contains",
"_targetUUID": "6d063d65-c11b-40c7-b004-c69b14776b9c",
"_targetIRI": "http://Orange.fr/Grenoble/BuildingF"
},
{
"_label": "ontologies_dogont_owl_contains",
"_targetUUID": "7d184940-bd65-43bd-bf6c-f2a5ee3519fb",
"_targetIRI": "http://Orange.fr/Grenoble/BuildingE"
},
{
"_label": "ontologies_dogont_owl_contains",
"_targetUUID": "7641a42c-16f6-4e93-83be-276290daeda8",
"_targetIRI": "http://Orange.fr/Grenoble/BuildingB"
},
{
"_label": "ontologies_dogont_owl_contains",
"_targetUUID": "a5fff4bf-ee65-40af-8261-2616892eb878",
"_targetIRI": "http://Orange.fr/Grenoble/BuildingA"
}
],
"address": "28 chemin Vieux Chêne, 38240 Meylan, FRANCE",
"_classes": ["http://elite.polito.it/ontologies/dogont.owl#Architectural"],
"industry": "Telecommunications"
}
]
},
{
"_depth": 1,
"_uuid": "a931394d-c072-4c58-b84e-a65b169e77ca",
"data": "string",
"_avatars": [
{
"_depth": 1,
"_iri": "http://Orange.fr/Grenoble/BuildingE",
"name": "Bâtiment E",
"_last_updated": 1523436278177,
"_uuid": "7d184940-bd65-43bd-bf6c-f2a5ee3519fb",
"_classes": ["http://elite.polito.it/ontologies/dogont.owl#Building"]
}
]
},
{
"_depth": 1,
"_uuid": "fbb86fd0-9397-4a18-92d1-73a6142004fb",
"data": "string",
"_avatars": [
{
"_depth": 1,
"_iri": "http://Orange.fr/Grenoble/BuildingB",
"name": "Bâtiment B",
"_last_updated": 1523436136447,
"_uuid": "7641a42c-16f6-4e93-83be-276290daeda8",
"_classes": ["http://elite.polito.it/ontologies/dogont.owl#Building"]
}
]
},
{
"_depth": 1,
"_uuid": "f7e924e5-98b4-4a2f-a75b-4a10356bbdc5",
"data": "string",
"_avatars": [
{
"_depth": 1,
"_iri": "http://Orange.fr/Grenoble/BuildingH",
"name": "Bâtiment H",
"_last_updated": 1523439069782,
"_uuid": "74355204-b8c9-4bc3-a889-f7c606a945c7",
"_classes": ["http://elite.polito.it/ontologies/dogont.owl#Building"]
}
]
}
],
"index": 0,
"size": 100
}
It’s clear to see the connection linked to other nodes from the avatar read.
To delete an avatar, unique UUID is required as well. Note that while deleting an avatar, the Response Code always responds 204 representing delete complete with no error. In case of some potential mistakes, after finishing DELETE procedure, it’s better to double check using GET API function.
Updating an avatar is also quite an important function as long as there’s a necessity or change of the whole structure. Similarly, unique UUID is needed for identifying a thing and payload includes all modification of the corresponding node. One more significant point is that after modification, the corresponding node will be assigned another relative UUID. As can be imagined, once the relative UUID is different, the links, connected to the node, created before will be erased as well. As a consequence, all nodes related to the updated node must be modified with the newly assigned relative UUID for links.
From the aspect of exploring the database, relative UUIDs of all nodes are listed in form of array. As long as they are needed, exploration can be done anytime. However, a unique UUID is the one required for reading, deleting, or updating an avatar and only shown once while an avatar is created. Of course there are other ways for retrieving the specific unique UUID, but the best way is not to lose them anyway.
Here you can find examples about avatar update updateAvatarSet.