Soporte de APIs OData V4

La plataforma Sofia2 ha incorporado un nuevo API de ontología de tipo ODATA V4. Open Data Protocol (OData) es un protocolo abierto que permite la creación y el consumo de API REST de una manera simple y estándar.

odata

 

OData tratar de dar solución a la exposición de orígenes de datos, relacionales o no, a través de un Servicio Web ejecutando operaciones con un lenguaje “estándar” basándose en:

  • La creación de un sistema uniforme de representación de datos estructurados a través de Atom o JSON (JavaScript Object Notation)
  • La utilización de convenciones URL uniformes tanto para la navegación, filtrado, orden y paginación de datos (entre otros)
  • La creación de operaciones uniformes dirigidas por dirección mediante las acciones GET, POST, PUT y DELETE.

A continuación se explica el procedimiento para dar de alta APIs de tipo OData en Sofia2 y el tipo de operaciones y queries que soporta actualmente:

 

Creación de un API de tipo OData V4

  1. Desde la consola accedemos al Api Manager para crear un API nuevo.
  2. En la pantalla de creación, aparece la opción OData, que actualmente solo está disponible para APIs de ontología. Al seleccionarlo, podemos comprobar que el endpoint base cambia.
  3. El resto de los pasos es común a todas las APIs.

 

Especificaciones de una URL OData

Una URL utilizada por un servicio de OData tiene a lo sumo tres partes importantes:

  • El endpoint base, que lo da la plataforma cuando se crea el API.
  • Parámetros de ruta (path parameters): Mediante variables separadas por “/”, a partir del endpoint base, sirven para identificar la ontología de la que se quiere recuperar la información, así como otras opciones.
  • Parámetros de consulta (query parameters): A partir de “?” forman un sistema de clave-valor, mediante el uso de unas palabras restringidas, y modelan la información que se recupera.

Parámetros de ruta (path parameters)

Siempre debe de indicar la ontología de la que está realizando la consulta. Se pueden realizar las siguientes consultas:

  • Recuperar toda la información de la ontología:

GET endpoint base/Nombre de la Ontología

odata1

 

  • Recuperar información de una instancia concreta:

GET endpoint base/Nombre de la Ontología(‘id de la instancia’)

 

  • Recuperar información de un campo en una instancia concreta:

GET endpoint base/Nombre de la Ontología(‘id de la instancia’)/Nombre del campo

Al consultar información estructurada en formato JSON, se pueden seleccionar campos que se encuentran a distintos niveles de JSONPath. Para ello, se delimita cada nivel por “/”.

 

Recuperar únicamente el valor de un campo en una instancia concreta:

GET endpoint base/Nombre de la Ontología(‘id de la instancia’)/Nombre del campo/$value

 

Recuperar el número de registros de la consulta:

GET endpoint base/Nombre de la Ontología/$count

 

Parámetros de consulta (query parameters)

Los parámetros que podemos utilizar en nuestra URL para realizar las consultas son:

 

 

Parámetros Descripción Opciones Ejemplo de uso
$orderby Ordena el resultado asc : ascentente

desc : descendente

ID = Alarma?$orderby=contextData.timestamp, contextData.user desc and contextData.kp asc
$filter Filtra los resultados con una condición boleana. eq: igual a

ne: diferente a

lt: menor que

le: menor igual que

gt: mayor que

ge: mayor igual que

and , or : unir operaciones

ID = Alarma?$filter=Alarma.mensajeAlarma ne “Alarma” and Alarma.causa ne “limite”
$select Da la proyección de un campo ID = Alarma?$select=Alarma.causa, Alarma.procedenciaAlarma

Los parámetros de consulta se colocan a continuación de “?” y se pueden concatenar mediante “&”.Por ejemplo,

ID = Alarma?$orderby=contextData.timestamp desc and contextData.user asc &$filter=Alarma.mensajeAlarma ne "Alarma" &$select=Alarma.causa, Alarma.procedenciaAlarma

 

También se pueden combinar los parámetros de tipo Path param, con los query Param. Por ejemplo, al caso anterior podemos incorporar $count para que haga un recuento de resultados de la consulta anterior:

ID = Alarma/$count?$orderby=contextData.timestamp desc and contextData.user asc &$filter=Alarma.mensajeAlarma ne "Alarma" &$select=Alarma.causa, Alarma.procedenciaAlarma

Del que obtenemos el siguiente resultado:

Más información sobre la convención de las URL en OData en http://docs.oasis-open.org/odata/odata/v4.0/odata-v4.0-part2-url-conventions.html

Soporte de APIs OData V4

Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión / Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión / Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión / Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión / Cambiar )

Conectando a %s