REST API Entidades: Crear una ontología desde una API REST y ejemplos de uso con FlowEngine y Dashboards

Este tipo de ontologías se crean a partir de una API REST externa a la plataforma. Los datos no serán almacenados en la plataforma, sino que todas las operaciones sobre estas ontologiás serán derivadas a la API REST.

Creación de ontologías REST.

Para crear una ontología basada en API REST, debes seguir los siguientes pasos:

Accede a la opción de menú DEVELOPMENT > Mis Ontologías
Aparecerá un listado con las ontologías ya existentes. En la esquina superior derecha selecciona el botón “Create”:
A continuación selecciona el tipo de ontología que vas a crear, en este caso Creación desde una API REST
Llegados a este punto, y tras rellenar nombre, descripción y demás información básica de la ontología, tienes dos opciones:
1. Rellenar la definición de la API REST a mano.
2. Obtener los datos de manera automática a través de un swagger Json que defina la API externa a utilizar.
  
  En este caso, para simplificar, opta por la segunda opción.
  Para ello, indica la URL de la definición Swagger de la API REST a usar de la siguiente manera:
  
  Tras hacer click en el botón Importar, aparecerá una ventana modal donde podrás seleccionar la definición (Esquema JSON) de entre todos los objetos definidos en la API:
  
  En este caso, selecciona el tipo Device. Tras aceptar la selección de la definición de objeto, verás que se han rellenado de manera automática las siguientes secciones:
  
  Nota: Todas estas secciones se pueden rellenar de manera manual o corregir sobre lo importado.
  1. URL base de la API REST:
  2. Autenticación: Se permite autenticación Basic y mediante Api Key.
    
    En este ejemplo, elige sin autenticación.
  3. Cabeceras: Puedes especificar las cabeceras que necesites para las llamadas a la API REST de la siguiente manera:
  4. Operaciones: En esta sección puedes definir/seleccionar las distintas operaciones de la API REST, así como darles un comportamiento por defecto dentro de la plataforma:
    
    Cada operación tendrá un path y método, así como un nombre. Además, tienes la posibilidad de asociar una función por defecto para cada operación. De esta manera la plataforma podrá tratar cada operación como las siguientes funciones:
    1. GET_ALL: Esta operación se usará para recuperar todos los elementos de la ontología. Será invocado en las sentencias SELECT por defecto.
    2. GET_BY_ID: Esta opción se usará para recuperar un único elemento por ID de la ontología. Será invocado en las sentencias SELECT ... WHERE ID=<value>
    3. DELETE_ALL: Esta opción se usará para eliminar todos los elementos de una ontología. Será invocado en las sentencias DELETE FROM <ontology>; (sin filtros).
    4. DELETE_BY_ID: Esta opción se usará para eliminar un único elemento de la ontología por ID. Será invocado en las sentencias DELETE FROM <ontology> WHERE ID=<value>
    5. UPDATE_BY_ID: Esta opción se usará para actualizar un único elemento de la ontología por ID. Será invocado en las sentencias UPDATE FROM <otology> SET ... WHERE ID=<value>
    6. INSERT: Esta opción se usará para insertar un nuevo objeto en una ontología. Será invocado en las sentencias INSERT INTO <ontology> ...
    No es necesario asignar un comportamiento por defecto a cada operación, aunque sí que es recomendable. Cuando vayas a hacer una consulta SQL, siempre puedes especificar la operación junto con la ontología. Por ejemplo:
    SELECT * from RestDevices.getDevicesUsingGet;
    En caso de que hubíeras asignado la función "GET_ALL" a la operación "getAllDevices", podrías hacer la consulta sin indicar la operación:
    
    SELECT * FROM RestDevices;
    
    Para asignar un tipo de operación por defecto (o para cambiar cualquier otro atributo), haz click en el icono de edición:
    
    De esta manera, los datos se cargarán en el formulario inferior, permitiéndote cambiar los atributos que estimes oportunos. En este ejemplo, puedes dar el comportamiento "GET_ALL" a la operación "getDevicesUsingGet":
    
    También es posible especificar los PATH y QUERY params de cada llamada. Puedes observarlo por ejemplo con la operación getDeviceByIdUsingGET, a la que le puedes asignar la funcionalidad "GET_BY_ID". En este caso, será obligatorio que la operación tenga un parámetro (da igual que sea path o query):
    
    Repitiendo estos pasos para todas las operaciones de actualización, inserción y borrado, quedarían de la siguiente manera:
  5. Esquema JSON: Al igual que para el resto de ontologías, necesitas un esquema JSON que defina el tipo de dato que tratará la ontología:
Guarda la definición de la ontología haciendo click en el botón Nuevo

Sentencias SQL sobre ontologías API REST

La ventaja del uso de este tipo de ontologías a la hora de atacar una API REST es que puedes hacerlo mediante lenguaje SQL, al igual que cualquier otra ontología, pero con algunas restricciones derivadas del uso de las APIs REST.

No se permitirá el uso de funciones, agregaciones ni JOINs en las sentencias, aunque sí que se permitirán filtros básicos (sin funciones) y selección de campos. Puedes resumir el subconjunto de ordenes SQL en función del tipo de sentencia:

SELECT

Donde los comparadores serán los símbolos: =, <, >, >=, >=, !=
INSERT
UPDATE
DELETE

Como ya comentamos anteriormente se puede seleccionar la operación en cada consulta de la siguiente manera:

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

Si no lo especificas, la plataforma buscará la operación que mejor se adapte a la consulta en base a la "función por defecto" que le hayamos asociado.

Imagina la siguiente consulta:

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

Dado que no indica la operación y que tiene un filtro por el campo id, la plataforma intentará buscar una operación del tipo GET_BY_ID. En el caso de no existir, usará una operación del tipo GET_ALL y aplicará el filtro a posteriori. Como se puede observar el, uso de la operación marcada como GET_BY_ID es mucho mas eficiente, de ahí que recomendemos marcar la funcionalidad de las operaciones que se den de alta en este tipo de ontologías.

IMPORTANTE: Como has podido ver, una operación puede tener tantos parámetros (path o query) asociados a campos como sean necesarios. En estos casos, si se combinan parámetros con otros campos en el filtrado, los operadores lógicos OR puede que sean cambiados por AND para poder ser coherentes con las llamadas REST.

Por ejemplo, si usas la operación "getDeviceByIdUsingGET" que tiene un parámetro (ID) y lanzas la siguiente consulta:

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

Dado que la operación requiere el uso del PathParam "id", el filtro description="Device 3" está ligado al resultado de la llamada REST con el id=2. Esto hace que la consulta se transforme realmente en :

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

En esta situación se podría usar una operación de tipo GET_ALL, con el operador OR sin problemas.

Ejemplos sobre ontologías REST en el FlowEngine:

Para empezar ve al menú y selecciona la opción "Mis Flujos Digitales":

Selecciona el dominio asociado a tu usuario:

Una vez dentro, vas a crear una serie de flujos para probar todos los tipos de operación puedes realizar sobre la ontología:

Ingesta de datos:

Para poder empezar, inserta una serie de datos a la ontología RestDevices, creada anteriormente a partir de una API REST.
1. Crea un nodo "Inject" en el que preparerás un JSON con todas las instancias de ontología que queremos insertar:
2. Crear un nodo "Insert" donde seleccionaremos la ontología hacia la que queremos hacer la ingesta. También pondremos un nodo debug para ver la salida:
3. Pulsa el botón "Deploy" para aplicar los cambios:
4. Una vez creados los nodos, haz click en la activación del nodo "Inject" para lanzar nuestro flujo de ingesta:
Consulta de datos: Una vez realizada la ingesta, vas a recuperar los datos que hay en la ontología RestDevices.
1. Sin filtros: Seleccionar todos los elementos de la ontología.
  1. Crea un nodo "Inject", para poder activar el flujo a mano.
  2. Crea un nodo "Query Static" donde indicarás la ontología sobre la que queremos consultar y la sentencia SQL:
    
    Al no indicar operación en la consulta, la plataforma tratará de utilizar aquella operación marcada como "GET_ALL".
  3. Crea un nodo "Debug" para poder ver el resultado de la query.
  4. Pulsa en el botón "Deploy" para guardar los cambios en el flujo.
  5. Pulsa en la activación del nodo "Inject" para lanzar la query:
  6. Puedes ver el resultado en la pestaña "Debug", situada a la derecha de la pantalla:
2. Filtrando:
  1. Crea un flujo exactamente igual que el anterior, pero cambiando la query por la siguiente:
  2. Si lanzas la consulta, verás que los resultados devueltos solamente contienen medidas del dispositivo "Device 1":
Actualización de datos:

Imagina que una de las medidas que se han ido insertando en la ontología no es correcta y quieres corregir el valor. Vas a crear un flujo que actualice el valor erróneo.
1. Crea un nodo "Inject", para poder activar el flujo a mano.
2. Crea un nodo "Query Static" donde indicarás la ontología sobre la que quieres 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. Crea un nodo "Debug" para poder ver el resultado de la query.
4. Pulsa 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. Crear un nodo "Inject", para poder activar el flujo a mano.
2. Crear un nodo "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 "DELETE_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 consulta.

Ejemplos sobre ontologías REST con Dashboards:

El objetivo final de este ejemplo es lograr crear un Dashboard que permita explorar la secuencia de medidas de cada dispositivo que tengas en tu ontología RestDevices. Para ello, sigue los siguientes pasos:

Crear un Datasource:
1. Ve al menú y selecciona "Mis DataSources":
2. Haz click en el botón de creación de DataSources:
3. Rellena los campos requeridos e indica la query:
4. Si pulsas en el botón "Ejecutar Consulta", podrás ver el resultado de la misma:
5. Haz click en el botón "Nuevo" para crear el DataSource.
Crear los Gadgets para el Dashboard:
1. Creación de una gráfica para representar las medidas en el tiempo.
  1. Ve al menú y selecciona la opción de "Mis Gadgets":
  2. Haz Click en el botón "Crear":
  3. Selecciona el DataSource y el tipo de Gadget
  4. Rellena el formulario para mostrar las medidas por timestamp, y pulsa en el botón "Nuevo" para crear el gadget de manera definitiva:
2. Gráfica para ver la última medida de cada dispositivo:
  1. Haz Click en el botón "Crear":
  2. Selecciona el DataSource y el tipo de Gadget:
  3. Rellena el formulario para añadir una medida y haz click en "Nuevo" para guardar el Gadget:
Crear el Dashboard:

Para crear el Dashboard, sigue los siguientes pasos:
1. Selecciona la opción "Mis Dashboards":
2. Pulsa en el botón "Crear":
3. Da nombre y descripción al Dashboard y haz click en "Nuevo":
4. A continuación, añade los Gadgets al dashboard, haciendo click en el botón "+":
  
  y compón el Dashboard de la siguiente manera:
5. Una vez hayas añadido los dos Gadgets, vas a enlazarlos para que, cuando se seleccione un dispositivo desde el PieChart, la gráfica muestre solamente las medidas de dicho dispositivo:
  1. Haz click en DataLink:
  2. Enlaza los campos "Description" del Gadget tipo Pie hacia el tipo Line:

platform-doc-es

REST API Entidades: Crear una ontología desde una API REST y ejemplos de uso con FlowEngine y Dashboards

Related content