Creating an ontology from a REST API and use examples with FlowEngine and Dashboards

This kind of ontologies are created from a REST API that's external to the platform. The data is not stored in the platform. Instead, all the operations on these ontologies are moved to the REST API.

REST ontology creation.

You must follow these steps to create a REST API-based ontology.

Access this menu option: DEVELOPMENT > My Ontologies
You will see a list with the existing ontologies. In the upper right corner, select the "Create" button:
Now, select the ontology type you will create, in this case Creation from a REST API
At this point, after filling in name, description and other basic info on the ontology, you have two choices:
1. Fill in the REST API definition manually.
2. Getting automatically the data using a JSON Swagger that defines the external API to be used.
  
  In this case, for the sake of simplicity, choose the second option..
  To do this, specifiy the REST API Swagger definition URL to be used like this:
  
  Click on the Importbutton and you will se ea modal window where you can select the definition (JSON Schema) among all the defined objects in the API:
  
  In this case, select the Device type. After selecting the object definition, you will see that the following sections have been automatically filled in:
  
  Note: All these sections can be manually filled in or edited to correct the imported information.
  1. REST API base URL:
  2. Authentication: Allowed options are Basic and using Api Key.
    
    In this example, select no authentication.
  3. Headers: You can specify the headers you'll need for the REST API like this:
  4. Operations: In this section, you can define/select the different REST API operations, and give them a default beahvior in the platform:
    
    Each operation will have a path and a method, along with a name. You can also associate a default function to each operation. The platform can deal with each operation as one of the following functions:
    1. GET_ALL: This option will be used to recover all the elements in an ontology. It will be invoked in the default SELECT options.
    2. GET_BY_ID:This option will be used to recover a single element, by ID, in the ontology. It will be invoked in the SELECT ... WHERE ID=<value> sentences.
    3. DELETE_ALL: This option will be used to delete all the elements in an ontology. It will be invoked in the DELETE FROM <ontology>; sentences (without filters).
    4. DELETE_BY_ID: This option will be used to delete a single element, by ID, in an ontology. It will be invoked in the DELETE FROM <ontology> WHERE ID=<value> sentences.
    5. UPDATE_BY_ID: This option will be used to update a single element, by ID, in an ontology. It will be invoked in the UPDATE FROM <otology> SET ... WHERE ID=<value> sentences.
    6. INSERT: This option will be used to insert a new object in an ontology. It will be invoked in the INSERT INTO <ontology> ... sentences.

1. 1. You do not need to assign a default behavior to every operation, but it is recommended. When you are going to do a SQL query, you can always specify the operation along with the ontology. E.g.
    SELECT * from RestDevices.getDevicesUsingGet;
    If you had assigned the "GET_ALL" function to the "getAllDevices" operations, you could do the query without specifying the operation:
    
    SELECT * FROM RestDevices;
    
    To assign a default operation type, or to change any other attribute, click on the Edition icon:
    
    In so doing, the data will be loaded in the lower form, allowing you to change the attributes you decide. In this example, you can give the "GET_ALL" behavior to the "getDevicesUsingGet" operation:
    
    You can also specify each call's PATH and QUERY params. You can see it, for instance, with the getDeviceByIdUsingGET operation, to which you can assign the "GET_BY_ID" functionality. In this case, it is mandatory for the operation to have a parameter (It can be either path or query):
    
    If you repeat these steps for all the addition, deletion and update operation, they will end up like this:
  2. JSON Schema: Same as in the other ontologies, you need a JSON Schema that defines the data type the ontology will deal with:
Save the ontology definition by clicking on the button:

SQL Sentences on REST API ontologies

The advantage of using this type of ontologies to attack a REST API is that you can use it with SQL language, same as with any other ontologies, but with a few restriction related to the use of REST APIs.

You are not allowed to use functions, aggregate or JOINs in the sentences, but you can use basic filters (without functions) and field selection. You can summarize the subset of SQL orders depending on the sentence type:

SELECT

where comparators are the following symbols: =, <, >, >=, >=, !=
INSERT
UPDATE
DELETE

As previously said, you can select the operation in each query like this:

SELECT [<FIELDS> | < * >] FROM <Ontology>.<operation>; por ejemplo: SELECT * FROM DeviceRest.getDevicesUsingGET;

If not specified, the platform will look for the operation best fitting to the query based on the "default function" you associated to it.

Imagine the following query:

SELECT id, measure FROM RestDevices where id="id_99";

As it does not specify the operation and it has a id-field filter, the platform will try and look for a GET_BY_ID type operation. If there is none, it will use a GET_ALL type operation and later apply the filter. As can be seen, the use of operations marked as GET_BY_ID is more efficient, so we recommend marking the functionality of the registered operations for this kind of ontologies.

IMPORTANT: As you have sene, an operation can have as many parameters associated to fields as required (path or query). In these cases, if you combine parameters with other fields in the filter, the OR logical operators can be replaced with AND to keep coherence with the REST calls.

For instance, if you use the "getDeviceByIdUsingGET" operation, with a parameter (ID), then run the following query:

SELECT * FROM RestDevices.getDeviceByIdUsingGET where id=2 OR description="Device 3";

As the operation requires using the PathParam "id", the filter description="Device 3" is linked to the result of the REST call with id=2. This causes the query to really become:

SELECT * FROM RestDevices.getDeviceByIdUsingGET where id=2 AND description="Device 3";

In this case, you could use a GET_ALL type operation, with the OR operator, without any problem.

Examples on REST ontologies in the FlowEngine:

Let's start by going to the menu and select "My Digital Flows" option:

Select the domain associated to your user:

Once there, you will create a number of flows to test all the operation types you can apply to the ontology:

Data ingestion

To start, insert a series of data to the RestDevices ontology, that was previously created from a REST API.
1. Create an "Inject" node on which you'll prepare a JSON with all the ontology instances you want to insert:
2. Create an "Insert" node where you will select the ontology toward which you want to make the ingestion. You will also add a debug node to see the output:
3. Click on the "Deploy" button to apply the changes:
4. Once the nodes have been crated, click on the "Inject" node activation to launch the ingestion flow:
Data query: Once the ingestion has been done, you will recover all the data in the RestDevices ontology.
1. Without filters: Select all the elements in the ontology.
  1. Create an "Inject" node, to manually start the flow.
  2. Create a "Query Static" node to specify the ontology you want to query and the SQL sentence:
    
    As you did not specify any operation in the query, the platform will try to use the operation marked as "GET_ALL".
  3. Create a "Debug" node to see the query's result.
  4. Click the "Deploy" button to save the changes in the flow.
  5. Click the "Inject" node's start to launch the query:
  6. You can see the result in the "Debug" tab, to the right of the screen:
2. Filtering:
  1. Create a flow exactly like the previous one, but with this other query:
  2. If you launch the query, you will the returned results only include the measurements from the "Device 1":
Data Update:

Imagine one of the measurements that were insterte din the ontology is not correct and you want to correct the value. You are going to create a flow that updates the wrong value.
1. Create an "Inject", para poder activar el flujo a mano.
2. Create a "Query Static" donde indicaremos la ontología sobre la que queremos actualizar y la sentencia SQL:
  
  Al no indicar operación en la consulta, la plataforma tratará de utilizar aquella operación marcada como "UPDATE_BY_ID".
3. Crear un nodo "Debug" para poder ver el resultado de la query
4. Pulsar en el botón "Deploy" para guardar los cambios en el flujo
5. Pulsar en la activación del nodo "Inject" para lanzar la query:
6. Podemos ver el resultado en la pestaña "Debug", situada a la derecha de la pantalla: Nos mostrará la cantidad de elementos afectados por la actualización
Borrado de datos:

Imaginemos que en vez de corregir una medida que haya llegado mal, queremos eliminarla. Vamos a crear un flujo que borre ese dato erróneo:
1. Create an "Inject" node, to manually start the flow.
2. Create a "Query Static" node to specify the ontology you want to query and the SQL sentence:
  
  As you did not specify any operation in the query, the platform will try to use the operation marked as "DELETE_BY_ID".
3. Create a "Debug" node to see the query's result.
4. Click the "Deploy" button to save the changes in the flow.
5. Click the "Inject" node's start to launch the query:
6. You can see the result in the "Debug" tab, to the right of the screen. It will show the amount of elements affected by the query.

Examples on REST ontologies with Dashboards:

The final goal in this example is creating a Dashboard that allows you explore the sequence of measurements from each device you have your RestDevices ontology. To do this, follow these steps:

Create un Datasource
1. Go to the menu and select "My DataSources"
2. Click the DataSources creation button:
3. Fill in the required fields and specify the query:
4. If you click the "Execute Query" button, you can see its results:
5. Click the "New" button to create the DataSource.
Create the Gadgets for the Dashboard:
1. Create a graph to represent the measurements in time:
  1. Go to the menu and select "My Gadgets":
  2. Click the "Create" button:
  3. Selet the DataSource and the Gadget type:
  4. Fill in the form to show the measurements per timestamp, then click on the "New" button to defintively create the Gadget:
2. Graph to see each device's last measurement:
  1. Click the "Create" button:
  2. Select the DataSource and the Gadget type:
  3. Fill in the form to add a measurement and click on "New" to save the Gadget:
Create the Dashboard

Follow these steps to create the Dashboard:
1. Select "My Dashboards":
2. Click the "Create" button
3. Give a name and adescription to the Dashboard, then click on "New":
4. Now add the Gadgets to the dashboard, by clicking on the "+" button:
  
  and make up the Dashboard like this:
5. Having added the two Gadgets, link them so that, whenever a device is selected from the PieChart, the graph shows only the measurements from that device:
  1. Click on DataLink:
  2. Link the Pie-type Gadget's "Description" fields to the Line type: