Manipulate Things

This article is to show how manipulating things in use of Ziggy Restful API which can be found at Develop > Thing’in API reference is going on. As can be imagined, manipulating things involves four phases: POST, DELETE, GET, and PUT. At the first step related to POST, things need to be created in order to manipulate an internet of things; then things which have been created can be further managed, modified, or even deleted through the rest of functions.

Manipulate “Things”

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

I. POST or to Create a single (or a set of) Thing(s)

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 things. 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 things is payload. As mentioned before, three kinds of relationships containing are elaborated or demonstrated: 1) all things alone, 2) architecture Orange Meylan connecting to seven buildings, and vice-versa, 3) seven buildings relating to architecture Orange Meylan.

1. All things alone

In all cases, some elements for creating a thing are required, i.e., projections containing at least an identifier ORI and category CLASS.

  • Orange Meylan
{
"data": "string",
"_projections": [
       {
         "_ori": "http://Orange.fr/Grenoble",
         "_class": "http://elite.polito.it/ontologies/dogont.owl#Architectural",
         "name": "Orange S.A.",
         "industry": "Telecommunications",
         "address": "28 chemin Vieux Chêne, 38240 Meylan, FRANCE"
       }
   ]
}
  • Building A / B /…
{
"data": "string",
"_projections": [
       {
         "_ori": "http://Orange.fr/Grenoble/BuildingA",
         "_class": "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 a thing, 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://ziggy-api-int.nprpaas.ddns.integ.dns-orange.fr/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.

2. Architecture Orange Meylan connecting to seven buildings

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.

  • Building A / B /…
{
"data": "string",
"_projections": [
       {
         "_ori": "http://Orange.fr/Grenoble/BuildingA",
         "_class": "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".

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.

  • Orange Meylan
{
"data": "string",
"_projections": [
       {
         "_ori": "http://Orange.fr/Grenoble",
         "_class": "http://elite.polito.it/ontologies/dogont.owl#Architectural",
         "name": "Orange S.A.",
         "industry": "Telecommunications",
         "address": "28 chemin Vieux Chêne, 38240 Meylan, FRANCE",
         "_outE": [
             {
               "_property": "ontologies_dogont_owl_contains",
               "_uuid": "a5fff4bf-ee65-40af-8261-2616892eb878",
               "_ori": "http://Orange.fr/Grenoble/BuildingA"
             },
             {
               "_property": "ontologies_dogont_owl_contains",
               "_uuid": "7641a42c-16f6-4e93-83be-276290daeda8",
               "_ori": "http://Orange.fr/Grenoble/BuildingB"
             },
             {
               "_property": "ontologies_dogont_owl_contains",
               "_uuid": "7d184940-bd65-43bd-bf6c-f2a5ee3519fb",
               "_ori": "http://Orange.fr/Grenoble/BuildingE"
             },
             {
               "_property": "ontologies_dogont_owl_contains",
               "_uuid": "6d063d65-c11b-40c7-b004-c69b14776b9c",
               "_ori": "http://Orange.fr/Grenoble/BuildingF"
             },
             {
               "_property": "ontologies_dogont_owl_contains",
               "_uuid": "65c0a6d8-7500-4b3f-9d5e-da7f5e71f71a",
               "_ori": "http://Orange.fr/Grenoble/BuildingG"
             },
             {
               "_property": "ontologies_dogont_owl_contains",
               "_uuid": "74355204-b8c9-4bc3-a889-f7c606a945c7",
               "_ori": "http://Orange.fr/Grenoble/BuildingH"
             },
             {
               "_property": "ontologies_dogont_owl_contains",
               "_uuid": "0954d38d-bfed-4302-8a8b-44fe2191eb41",
               "_ori": "http://Orange.fr/Grenoble/BuildingI"
             }
          ]
       }
   ]
}

The third case is just the inverse case which is then be omitted here.

II. GET or to Read a Thing

In order to get to read a thing, the corresponding unique UUID is required along with the Namespace. 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",
     "_projections": [
       {
         "_depth": 0,
         "_ori": "http://Orange.fr/Grenoble/BuildingA",
         "name": "Bâtiment A",
         "_last_updated": 1523436043159,
         "_uuid": "a5fff4bf-ee65-40af-8261-2616892eb878",
         "_class": "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,
         "_ori": "http://Orange.fr/Grenoble/BuildingI",
         "name": "Bâtiment I",
         "_last_updated": 1523439096390,
         "_uuid": "0954d38d-bfed-4302-8a8b-44fe2191eb41",
         "_class": "http://elite.polito.it/ontologies/dogont.owl#Building"
       }
     ]
   },
   {
     "_depth": 1,
     "_uuid": "831e2933-43a9-44d1-930b-b4f74a15d096",
     "data": "string",
     "_projections": [
       {
         "_depth": 1,
         "_ori": "http://Orange.fr/Grenoble/BuildingF",
         "name": "Bâtiment F",
         "_last_updated": 1523438940263,
         "_uuid": "6d063d65-c11b-40c7-b004-c69b14776b9c",
         "_class": "http://elite.polito.it/ontologies/dogont.owl#Building"
       }
     ]
   },
   {
     "_depth": 1,
     "_uuid": "551b2244-2952-4d58-8b23-e522299799b1",
     "data": "string",
     "_projections": [
       {
         "_depth": 1,
         "_ori": "http://Orange.fr/Grenoble/BuildingG",
         "name": "Bâtiment G",
         "_last_updated": 1523438986647,
         "_uuid": "65c0a6d8-7500-4b3f-9d5e-da7f5e71f71a",
         "_class": "http://elite.polito.it/ontologies/dogont.owl#Building"
       }
     ]
   },
   {
     "_depth": 1,
     "_uuid": "9a074188-c35a-4111-91b8-aa9cb4bc386b",
     "data": "string",
     "_projections": [
       {
         "_depth": 1,
         "_ori": "http://Orange.fr/Grenoble/BuildingA",
         "name": "Bâtiment A",
         "_last_updated": 1523436043159,
         "_uuid": "a5fff4bf-ee65-40af-8261-2616892eb878",
         "_class": "http://elite.polito.it/ontologies/dogont.owl#Building"
       }
     ]
   },
   {
     "_depth": 0,
     "_uuid": "fff70768-42b9-4882-a0f5-9cc3d0b1b326",
     "data": "string",
     "_projections": [
       {
         "_depth": 0,
         "_ori": "http://Orange.fr/Grenoble",
         "name": "Orange S.A.",
         "_last_updated": 1523439314455,
         "_uuid": "76a5f516-4038-4322-8214-8475835ebfb0",
         "_outE": [
           {
             "_property": "ontologies_dogont_owl_contains",
             "_uuid": "0954d38d-bfed-4302-8a8b-44fe2191eb41",
             "_ori": "http://Orange.fr/Grenoble/BuildingI"
           },
           {
             "_property": "ontologies_dogont_owl_contains",
             "_uuid": "74355204-b8c9-4bc3-a889-f7c606a945c7",
             "_ori": "http://Orange.fr/Grenoble/BuildingH"
           },
           {
             "_property": "ontologies_dogont_owl_contains",
             "_uuid": "65c0a6d8-7500-4b3f-9d5e-da7f5e71f71a",
             "_ori": "http://Orange.fr/Grenoble/BuildingG"
           },
           {
             "_property": "ontologies_dogont_owl_contains",
             "_uuid": "6d063d65-c11b-40c7-b004-c69b14776b9c",
             "_ori": "http://Orange.fr/Grenoble/BuildingF"
           },
           {
             "_property": "ontologies_dogont_owl_contains",
             "_uuid": "7d184940-bd65-43bd-bf6c-f2a5ee3519fb",
             "_ori": "http://Orange.fr/Grenoble/BuildingE"
           },
           {
             "_property": "ontologies_dogont_owl_contains",
             "_uuid": "7641a42c-16f6-4e93-83be-276290daeda8",
             "_ori": "http://Orange.fr/Grenoble/BuildingB"
           },
           {
             "_property": "ontologies_dogont_owl_contains",
             "_uuid": "a5fff4bf-ee65-40af-8261-2616892eb878",
             "_ori": "http://Orange.fr/Grenoble/BuildingA"
           }
         ],
         "address": "28 chemin Vieux Chêne, 38240 Meylan, FRANCE",
         "_class": "http://elite.polito.it/ontologies/dogont.owl#Architectural",
         "industry": "Telecommunications"
       }
     ]
   },
   {
     "_depth": 1,
     "_uuid": "a931394d-c072-4c58-b84e-a65b169e77ca",
     "data": "string",
     "_projections": [
       {
         "_depth": 1,
         "_ori": "http://Orange.fr/Grenoble/BuildingE",
         "name": "Bâtiment E",
         "_last_updated": 1523436278177,
         "_uuid": "7d184940-bd65-43bd-bf6c-f2a5ee3519fb",
         "_class": "http://elite.polito.it/ontologies/dogont.owl#Building"
       }
     ]
   },
   {
     "_depth": 1,
     "_uuid": "fbb86fd0-9397-4a18-92d1-73a6142004fb",
     "data": "string",
     "_projections": [
       {
         "_depth": 1,
         "_ori": "http://Orange.fr/Grenoble/BuildingB",
         "name": "Bâtiment B",
         "_last_updated": 1523436136447,
         "_uuid": "7641a42c-16f6-4e93-83be-276290daeda8",
         "_class": "http://elite.polito.it/ontologies/dogont.owl#Building"
       }
     ]
   },
   {
     "_depth": 1,
     "_uuid": "f7e924e5-98b4-4a2f-a75b-4a10356bbdc5",
     "data": "string",
     "_projections": [
       {
         "_depth": 1,
         "_ori": "http://Orange.fr/Grenoble/BuildingH",
         "name": "Bâtiment H",
         "_last_updated": 1523439069782,
         "_uuid": "74355204-b8c9-4bc3-a889-f7c606a945c7",
         "_class": "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 thing read.

III. DELETE or to Delete a Thing

To delete a thing, unique UUID is required as well. Note that while deleting a thing, 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.

IV. PUT or to Update a Thing

Updating a thing 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 a thing and only shown once while a thing is created. Of course there are other ways for retrieving the specific unique UUID, but the best way is not to lose them anyway.