Para la implementación de servicios web basados en REST, Omnis Studio dispone de un componente externo y un “plugin” encargado de publicar el código Omnis como Servicio Web, ambos son complementados mediante el nuevo componente externo JSON denominado “OJSON”, que permite la adecuada gestión de objetos basados en JSON, profusamente utilizados con REST.
¿Qué es REST? REST es sin lugar a dudas el modelo más extendido hoy en día para usar y publicar servicios web, está considerado como la mejor alternativa al uso de otras tecnologías como SOAP. Un servicio web RESTful es identificado mediante una URI, donde los clientes interactúan con el recurso a través de solicitudes HTTP, obteniendo respuestas mediante un conjunto ya predeterminado de métodos HTTP.
Creación de un “Web Service” cliente
Dentro del grupo de objetos externos “Web Worker Objects”, podemos encontrar el “HTTPClientWorker” que es un objeto de tipo “Worker”. Esto significa que funciona de modo similar a como lo hacen los ya conocidos objetos DAM de este mismo tipo, es decir que son ejecutados en segundo plano.
Para utilizar el objeto, deberemos crear una “Object Class” con el “HTTPClientWorker” como subclase. Tal como mostramos en la siguiente imagen:
En la clase-objeto así creada, será necesario definir dos métodos, “$completed” y “$cancelled”, los cuales serán respectivamente invocados tras la obtención del resultado de una solicitud o al producirse su cancelación. A continuación, deberemos crear una variable-instancia de tipo objeto sobre una clase “remote-form” JavaScript, desde donde poder instanciar la clase-objeto anteriormente creada, con la finalidad de poder interactuar con el servicio Web mediante sus métodos. De entre ellos el objeto “HTTPClientWorker” incluye: El “$init()” que lo inicializa de forma que quede listo para realizar las peticiones HTTP que se especifiquen; El “$run()” que ejecuta un hilo en primer plano; El “$start()” que ejecuta un hilo en segundo plano y el “$cancel()” que cancela el subproceso en marcha. El método “$cancel()” es invocado cuando se cancela la solicitud y el “$completed()” cuando se complete la solicitud, la cual retornará una única variable-parámetro de tipo “row” con diversas columnas, el contenido de la respuesta estará incluido en la última columna.
Ejemplo de cliente “Web Sercice” basado en REST.
Desde la web de Aula Omnis, podrá descargar una librería dispuesta a modo de ejemplo, sobre el uso de un Servicio Web basado en REST.
Dicha librería permite mostrar información básica sobre la previsión del tiempo, mediante el acceso a un servicio web público proporcionado por WorldWeatherOnline.com. La compañía ofrece dos versiones de su API; una gratuita y otra de pago. El ejemplo se basa en el servicio gratuito, éste puede ser invocado con un límite de 12.000 accesos diarios y 5 veces por segundo, lo cual es más que suficiente para nuestro propósito. Para hacer uso del servicio, deberá obtener antes una clave de la API desde WorldWeatherOnline.com e introducirla al ejecutar la librería por primera vez.
Para probar el servicio y conseguir mostrar el pronóstico del tiempo, abra primero la librería de ejemplo, haga clic derecho sobre el “remote-form” “jsWeather” y seleccione “Test Form” desde el menú contextual. El formulario deberá abrirse en su navegador y mostrar el pronóstico del tiempo para 5 días en Saxmundham. Tenga en cuenta que se ésta utilizando la versión gratuita de la API, la cual tiene un límite de 5 consultas por segundo, por lo que se hace uso de un temporizador para evitar la devolución de un error desde el servidor. Si publica el formulario a un servidor web, el servicio tratará de identificar su ubicación mediante su dirección IP en uso.
Cuando examine el código de la librería de ejemplo, notará que los métodos clave son “GetWeather”, “getData”, “readCurrentData” y “readForecastData” en el caso del “remote-form” “jsWeather”. “$completed, “$returnVa” en el caso de la clase-objeto “Orest”. A continuación mostramos el método de iniciación “$init()” encargado de inicializar el objeto “Web Services”, configurando los parámetros principales e invocando el servicio web.
; iURI (Char) inicializado como "http://api.worldweatheronline.com"
; iHTTPMethod (Int) iniciado con el valor “kOWEBhttpMethodGet”
; iHeadersList (List)
; iContentChar (Char)
Do iHeadersList.$define(iHeaderName,iHeaderValue)
; call the web service
Do iRestfulObj.$init(iURI,iHTTPMethod,iHeadersList,iContentChar)
Do iRestfulObj.$run() Returns lStatus
A continuación mostramos, el método “$completed” del objeto “Orest”:
; invocado desde el “worker” del cliente con los resultados
Calculate iResponse as pRow
Calculate iResponseHeaders as pRow.responseHeaders
Do OJSON.$formatjson(pRow.responseContent) Returns iReturnStr
Do OJSON.$jsontolistorrow(pRow.responseContent) Returns iJSONRow
Para procesar la salida que nos llega en formato JSON, se hace uso del nuevo componente externo “OJSON”.
Creando nuestros propios “Web Services”
Un plug-in “Web Server” permite publicar el código de nuestras aplicaciones Omnis, que permitirá a los posibles cliente hacer uso de nuestros “Web Services”. La interfaz para éstos servicios web es vista por los clientes como una API o conjunto de APIs. Omnis genera las API’s RESTful (o ORAs) usando una definición "Swagger", que es el estándar más utilizado con las API’s RESTful.
Podrá ver las Omnis APIs RESTul desde el navegador de Omnis Stido (Studio Browser) como hijos del nodo de su librería bajo el grupo “Web Service Server” (tal cómo ya venia ocurriendo con los servicios basados en WSDL). Cada “ORA” se muestra bajo un nodo separado en el árbol, y varias opciones o acciones con hipervínculos. Podrá ver su definición “Swagger” navegando a trabes de los hipervínculos.
Para probar el servicio y conseguir mostrar el pronóstico del tiempo, abra primero la librería de ejemplo, haga clic derecho sobre el “remote-form” “jsWeather” y seleccione “Test Form” desde el menú contextual. El formulario deberá abrirse en su navegador y mostrar el pronóstico del tiempo para 5 días en Saxmundham. Tenga en cuenta que se ésta utilizando la versión gratuita de la API, la cual tiene un límite de 5 consultas por segundo, por lo que se hace uso de un temporizador para evitar la devolución de un error desde el servidor. Si publica el formulario a un servidor web, el servicio tratará de identificar su ubicación mediante su dirección IP en uso.
Cuando examine el código de la librería de ejemplo, notará que los métodos clave son “GetWeather”, “getData”, “readCurrentData” y “readForecastData” en el caso del “remote-form” “jsWeather”. “$completed, “$returnVa” en el caso de la clase-objeto “Orest”. A continuación mostramos el método de iniciación “$init()” encargado de inicializar el objeto “Web Services”, configurando los parámetros principales e invocando el servicio web.
; iURI (Char) inicializado como "http://api.worldweatheronline.com"
; iHTTPMethod (Int) iniciado con el valor “kOWEBhttpMethodGet”
; iHeadersList (List)
; iContentChar (Char)
Do iHeadersList.$define(iHeaderName,iHeaderValue)
; call the web service
Do iRestfulObj.$init(iURI,iHTTPMethod,iHeadersList,iContentChar)
Do iRestfulObj.$run() Returns lStatus
A continuación mostramos, el método “$completed” del objeto “Orest”:
; invocado desde el “worker” del cliente con los resultados
Calculate iResponse as pRow
Calculate iResponseHeaders as pRow.responseHeaders
Do OJSON.$formatjson(pRow.responseContent) Returns iReturnStr
Do OJSON.$jsontolistorrow(pRow.responseContent) Returns iJSONRow
Para procesar la salida que nos llega en formato JSON, se hace uso del nuevo componente externo “OJSON”.
Creando nuestros propios “Web Services”
Un plug-in “Web Server” permite publicar el código de nuestras aplicaciones Omnis, que permitirá a los posibles cliente hacer uso de nuestros “Web Services”. La interfaz para éstos servicios web es vista por los clientes como una API o conjunto de APIs. Omnis genera las API’s RESTful (o ORAs) usando una definición "Swagger", que es el estándar más utilizado con las API’s RESTful.
Podrá ver las Omnis APIs RESTul desde el navegador de Omnis Stido (Studio Browser) como hijos del nodo de su librería bajo el grupo “Web Service Server” (tal cómo ya venia ocurriendo con los servicios basados en WSDL). Cada “ORA” se muestra bajo un nodo separado en el árbol, y varias opciones o acciones con hipervínculos. Podrá ver su definición “Swagger” navegando a trabes de los hipervínculos.