Conociendo las APIs de SOFIA 2 – API RESTFul

SOFIA2 proporciona un conjunto de APIS que permitirán a las aplicaciones cliente o Knowledge Processor (KPs), enviar y consumir información en la plataforma.

En este post vamos a introducir el API RESTFul de SOFIA2, cuya documentación on-line la podemos consultar en la dirección: http://sofia2.com/sib/

El protocolo del API RESTFul de SOFIA2 difiere del resto de APIS debido a las características intrínsecas de la especificación RESTFul y la necesidad de manejar recursos a través de los verbos HTTP. En este sentido, este API no utiliza el protocolo estándar SSAP que introdujimos en el post https://about.sofia2.com/2014/04/14/conociendo-el-protocolo-de-interoperabilidad-de-sofia2-ssap/, sino que maneja un objeto o recurso denominado SSAPResource a través de las operaciones HTTP: POST, PUT, GET y DELETE.

El recurso SSAPResource tiene las siguientes propiedades:

Lo que permite cubrir el juego de operaciones SSAP de la siguiente forma:

Operación SSAP Operación RESTFul
JOIN HTTP POST enviando un SSAPResource informando:

· join: true

· instanceKP: Identificador de KP e indentificador de instancia de KP

· token: Token de autenticación

LEAVE HTTP POST enviando un SSAPResource informando:

· leave: true

· sessionkey: Clave de sesión a caducar

INSERT HTTP POST enviando un SSAPResource infomando:

· ontology: Ontologia sobre la que envia una nueva instancia.

· data: Intancia de ontologia enviada.

· dessionkey: clave de sesión SSAP en la que pertenece el mensaje

HTTP GET enviando un SSAPResource informando a traves de los queryParams de la URL:

· $ontology: Ontologia sobre la que envia una nueva instancia.

· $query: Sentencia SQLLIKE de tipo INSERT.

· $sessionKey: clave de sesión SSAP en la que pertenece el mensaje

· $queryType: SQLLIKE

UPDATE HTTP PUT enviando un SSAPResource infomando:

· ontology: Ontologia sobre la que se realiza la actualización.

· Data: Intancia de ontologia con datos actualizados.

· Sessionkey: clave de sesión SSAP en la que pertenece el mensaje

HTTP GET informando a traves de los queryParams de la URL:

· $ontology: Ontologia sobre la que se realiza la actualización.

· $query: Sentencia SQLLIKE de tipo UPDATE.

· $sessionKey: clave de sesión SSAP en la que pertenece el mensaje

· $queryType: SQLLIKE

DELETE HTTP DELETE enviando un SSAPResource infomando:

· ontology: Ontologia sobre la que se realiza el borrado.

· Data: Intancia de ontologia a borrar.

· Sessionkey: clave de sesión SSAP en la que pertenece el mensaje

HTTP DELETE informando a traves de pathParam: el objectId en BDTR de la instancia de ontologia a borrar. Y a traves de queryParams de la URL:

· $ontology: Ontologia sobre la que se realiza el borrado.

· $sessionKey: clave de sesión SSAP en la que pertenece el mensaje

HTTP GET informando a traves de los queryParams de la URL:

· $ontology: Ontologia sobre la que se realiza el borrado.

· $query: Sentencia SQLLIKE de tipo DELETE.

· $sessionKey: clave de sesión SSAP en la que pertenece el mensaje

· $queryType: SQLLIKE

QUERY HTTP GET informando a traves de los queryParams de la URL:

· $ontology: Ontologia sobre la que se realiza la consulta.

· $query: Sentencia de consulta

· $sessionKey: clave de sesión SSAP en la que pertenece el mensaje

· $queryType: Tipo de lenguaje de consulta

· $queryParams: Parámetros a informar en caso de consulta predefinida en el SIB con argumentos.

HTTP GET informando a traves de pathParam: el objectId en BDTR de la instancia de ontologia a consultar. Y a traves de queryParams de la URL:

· $ontology: Ontologia sobre la que se realiza la consulta.

· $sessionKey: clave de sesión SSAP en la que pertenece el mensaje

GET_CONFIG HTTP GET informando a traves de los queryParams de la URL:

· $kp: Identificador de KP del que se quiere recuperar su configuración

· $instanciaKp: Identificador de la instancia de KP de la que se quiere recuperar su configuración

· $token:Token de autenticación

Las operaciones SSAP relativas a la suscripción (SUBSCRIBE, UNSUBSCRIBE e INDICATION) no están soportadas en este API, ya que REST no permite mantener una conexión bidireccional con el cliente.

En http://sofia2.com el API RESTFul se expone en el path http://sofia2.com/sib/services/api_ssap/v01/SSAPResource

Los métodos HTTP expuestos por el API son:

· POST: Método que permite enviar un recurso SSAPResource en formato JSON, cubriendo las operaciones JOIN, LEAVE e INSERT. El resultado será otro recurso SSAPResource indicando:

o En operaciones JOIN: SessionKey asignada por el SIB:

o En operaciones INSERT: ObjectId asignado en BDTR a la instancia de ontologia insertada:

o En operaciones LEAVE: Respuesta vacía, indicándose si todo ha ido bien a traves del código de error HTTP 200 OK:

La documentación on-line completa del método POST describe los posibles códigos de error, así como incluye ejemplos de invocación:

· PUT: Método que permite enviar un recurso

SSAPResource informando una instancia de ontología existente en la BDTR para su actualización con nuevos valores. El recurso enviado, está en formato JSON y la instancia de ontología se identifica a través del ObjectId en BDTR:

{

"sessionKey":"<session_key>",

"ontology":"SensorTemperatura",

"data":"{"_id":{"$oid": "527a6352c0af4380e54822e1”, <instancia_ont>}"

}

El resultado será una respuesta vacía indicándose si todo ha ido bien a través del código de error HTTP 200 OK:

La documentación on-line completa del método PUT describe los posibles códigos de error, así como incluye ejemplos de invocación:

· GET: Método que permite realizar las operaciones QUERY sobre BDTR y BDH. Y de operaciones GET_CONFIG. PermiteAdemás, mediante lenguaje SQLLIKE y sentencias de tipo INSERT,UPDATE y DELETE realizar operaciones de estos tipos sobre la BDTR.

El resultado será un objeto SSAPResource con los datos correspondientes a la consulta.

o QUERY sobre BDTR y BDH: Tiene dos variantes:

§ Mediante el ObjectID como pathParam permite recuperar de la BDTR la instancia de ontologia con dicho ObjectID. Este método necesita además recibir como queryParams:

· $sessionKey de la sessión SSAP

· $ontologia sobre la que se realiza la operación.

La documentación on-line completa del método GET recibiendo el ObjectId por PathParam describe los posibles códigos de error, así como incluye ejemplos de invocación:

§ Mediante sentencia a ejecutar sobre la base de datos correspondiente. Este método recibe los siguientes parámetros como queryParams:

· $ontology: Ontologia sobre la que se realiza la consulta.

· $query: Sentencia de consulta

· $sessionKey: clave de sesión SSAP en la que pertenece el mensaje

· $queryType: Tipo de lenguaje de consulta. Puede tomar valores

o NATIVE: Sentencia a ejecutar sobre la BDTR utilizando lenguaje nativo en la sentencia indicada en el argumento $query

o SQLIKE: Sentencia a ejecutar sobre la BDTR utilizando lenguaje SQLLIKE en la sentencia indicada en el argumento $query

o SIB_DEFINED: Sentencia a ejecutar sobre la BDTR utilizando una sentencia predefinida en el SIB. En este caso el argumento $query será el identificador de la sentencia.

o BDH: Sentencia a ejecutar sobre la BDH utilizando una sentencia en lenguaje SQL de la BDH en el argumento $query.

· $queryParams: Parámetros a informar en caso de consulta predefinida en el SIB con argumentos.

La documentación on-line completa del método GET describe los posibles códigos de error, así como incluye ejemplos de invocación:

o GET_CONFIG: El path de esta operación es http://sofia2.com/sib/services/api_ssap/v01/SSAPResource/configPermite recuperar la configuración de un KP, informando a través de los queryParams de la URL:

§ $kp: Identificador de KP del que se quiere recuperar su configuración

§ $instanciaKp: Identificador de la instancia de KP de la que se quiere recuperar su configuración

§ $token: Token de autenticación

La documentación on-line completa del método GET para configuración describe los posibles códigos de error, así como incluye ejemplos de invocación:

· DELETE: Método que permite realizar las operaciones de borrado sobre la BDTR.

La respuesta será vacia, indicándose si la operación ha sido correcta a traves del código de error HTTP 200 OK.

Tiene dos variantes:

o Mediante el ObjectID como pathParam: Permite borrar en la BDTR la instancia de ontología con dicho ObjectID. Este método necesita además recibir como queryParams:

§ $sessionKey de la sesion SSAP

§ $ontologia sobre la que se realiza la operación.

La documentación on-line completa del método DELETE recibiendo el ObjectId por Pathparam describe los posibles códigos de error, así como incluye ejemplos de invocación:

o Enviando un recurso SSAPResource informando la instancia de ontología existente en la BDTR para su borrado. El recurso enviado, está en formato JSON y la instancia de ontología se identifica a través del ObjectId en BDTR:

{

"sessionKey":"<session_key>",

"ontology":"SensorTemperatura",

"data":"{"_id":{"$oid": "527a6352c0af4380e54822e1”}"

}

La documentación on-line completa del método DELETE describe los posibles códigos de error, así como incluye ejemplos de invocación:

Conociendo las APIs de SOFIA 2 – API RESTFul

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