Exponiendo Servicios REST con JSON usando SOA Suite 12c

Hay dos tipos de Servicios Web: SOAP y REST. Por lo general, en el día a día con Oracle SOA Suite nos ocupamos de los servicios web SOAP, pero también se pueden crear servicios web RESTful.

Los servicios web RESTful están diseñados para funcionar mejor en la Web. REpresentational State Transfer (REST) es lo que sus siglas significan y es un estilo arquitectónico. En REST, los datos se pueden transmitir a través de una interfaz estandarizada (como HTTP).


Introducción

El Adaptador REST de SOA Suite 12c recientemente presentado brinda opciones para llamar a servicios RESTful pero también se puede usar para exponer servicios RESTful. Estos servicios expuestos pueden usar tanto XML o JSON como formato de intercambio de mensajes. El soporte de JSON se implementa mediante la implementación de NXSD (archivos de definición de esquema de Native Format Builder, más información aquí) para describir el mensaje JSON y hacer posible la transformación hacia y desde XML. Este XML puede ser utilizado como de costumbre por los diferentes componentes de una aplicación SOA (composite). 



Entendiendo JSON

• JSON: significa JavaScript Object Notation.
• JSON: es una sintaxis para almacenar e intercambiar datos.
• JSON: es texto, escrito con notación de objetos JavaScript.

Para entender mejor que és JSON y como usarlo, vaya al siguiente enlance: https://www.w3schools.com/js/js_json_intro.asp



Primer contacto, ejercicio: Hola Mundo

Usando WADL

Un archivo WADL (Web Application Description Language) para servicios REST se puede comparar con un archivo WSDL para servicios SOAP. Al igual que con los servicios SOAP, el uso de un archivo de definición predefinido facilita la configuración. Esto es especialmente cierto cuando se llaman servicios REST. Si hay una WADL disponible, úselo. Es más probable que sea más completo que lo que puedes crear tú mismo. Cuando no hay WADL disponible, se puede usar una herramienta de terceros para generar un WADL.

1_Abra JDeveloper y cree una aplicación SOA con un Proyecto vacío dentro:

2_ Arrastre y suelte un Adaptador REST al carril de Servicios:

3_ Asignele un nombre y tipo al servicio:

4_ En este punto se configurarán varias cosas: Description, Path de Recursos y Método con request/response asociados:

4.1_ Asignar una descripción al servicio (esta descripción formará parte del endpoint del servicio), el path de recursos dejarlo por defecto en raiz ('/', si lo desea puede especificar un path mas descriptivo) y hacer clic en el botón con simbolo + en color verde para añadir un nuevo método:

Los métodos se asemejan a una operación de una aplicación SOA, es decir, asi como en un proceso BPEL puede tener varias operaciones, un servicio REST puede tener varios métodos.

4.2_  En la pestaña 'Request', darle un nombre al método, usar el verbo HTTP GET, y crear un nuevo parametro de entrada (este parámetro se usara para definir el mensaje de entrada (request) y formará parte del esquema asociado al mismo):

4.3_ Luego en la pestaña 'Reponse' habilitar mensajes JSON haciendo clic en el checkbox tanto para una respuesta exitosa (Success) como para una respuesta de fallo (Failure):

5_ Finalmente haga clic en "Finish" para finalizar la creación de la interfaz, esto generará un archivo WADL que será el contrato de nuestro servicio. Al igual que un WSDL el archivo WADL también tiene su estructura:

Veamos el contenido del archivo WADL:

Si prestamos atención, se definen muy sencillamente las partes del servicio... por un lado esta el Nombre y Descripción del servicio (elemento <doc title=''/>) esto formará parte del endpoint con el que se podra consumir mas tarde el servicio. Por otro lado, esta el path de recursos... que no es mas que una forma de organizar los métodos en caso de tener varios dentro de un mismo servicio (el path de recursos tambien conforma el endpoint consumible del servicio), También se define el verbo HTTP empleado para realizar la llamada y finalmente los diferentes mensajes: (request/response + fault) en el mismo orden en que aparecen en el WADL.

Los mensajes response y failure (los ultimos dos al final del documento) declaran que devolverán un mensaje JSON estandar (no definen la estructura porque como se dijo antes... un JSON es un texto).

Este documento WADL se puede modificar a mano ante necesidades de modificaciones.



5_ Insertar un proceso BPEL para el servicio REST, para ello, hacer clic derecho en el carril de componentes y luego sobre la opción 'BPEL Process':

6_ Configurar el BPEL configurandole un nombre, tipo de template y asociandole el WADL:

6.1_ Para asociar el WADL, expandir el nodo "Services" y seleccionar el WADL anteriormente creado haciendo clic en OK:

Finalizar la creación del BPEL haciendo clic nuevamente en OK.



7_ Una vez creado el BPEL, con una actividad "Assign" vamos a concatenar un prefijo "Hola " al parametro de entrada para de esta forma lograr un simple Hola Mundo!. Para esto, arrastre  y suelte una actividad Assign dentro del BPEL entre las actividades Receive1 y Reply1:

8_ Abrir la actividad Assign y mapear el parametro de entrada a la variable de salida:

Como se puede apreciar, al realizar el mapeo... no se visualizan los elementos internos del JSON. Esto es porque como dijimos anteriormente, el mensaje JSON es un texto (un string, una cadena). Esto quiere decir que tendremos que editar el mapeo a mano tanto el origen (source) como el destino (target). Y también estamos viendo como se llaman las variables de entrada (input variable) y de salida (output variable), que son "process.inputVar" y "process.outputVar" respectivamente.


9_ Editar origen (source) del mapeo, esto es, concatenar un "Hola " al parametro de entrada (que si recuerdan... se llamaba "nombre" en minúscula (si no recuerda, haga clic aqui para revisarlo)). Para editar el origen del mapeo hacer clic derecho sobre el icono de operacion y seleccionar la opción "Edit 'From' Expression":

Y añadimos "Hola " + adelante (antes) de la variable "process.inputVar" y además un .nombre al final (despues) de la variable:

Editar tambien el destino (target) haciendo clic sobre el icono de operacion y seleccionando "Edit 'To' Expression" y añadir .Saludo al final de la variable "process.outputVar":

Si prestan atención, la variable de salida esta definida como un mensaje JSON (muy genericamente) es decir, no posee una estructura previamente definida. Agregandole .Saludo a la variable de salida, estamos creando un elemento "Saludo" al que le asignaremos un dato (resultado de concatenar "Hola " con lo que recibe el parametro de entrada del servicio).


Deployar y Probar

Ya esta todo listo para deployar la aplicación y probarla.

Una vez deployada, abrir la consola del Enterprise Manager (EM Console) y testear el servicio:

Obteniendo URL

En la misma consola EM, cuando se va a probar el servicio... al hacer clic en el botón Test, la misma consola nos brinda automaticamente la URL para el servicio. Esta URL nos sirve para quien nos quiera consumir no llame.

Para probar esto, usar SoapUI y realizar la prueba:

Recuerda que al importar el servicio REST, elimina la ultima parte de la URL: /application.wadl debe eliminarse.

Luego añadir el parametro de entrada "nombre" haciendo clic en el boton + de color verde y asignandole algun valor:

Al realizar una petición, haciendo clic en el boton verde (play) veremos como responde el mensaje JSON:

En proximos articulos detallaremos como consumir otros servicios REST con JSON, como comunicarse con una base de datos y como hacer transformacion de mensajes JSON con modulos JavaScript.

Cualquier duda puede debatirse libremente con respeto en los comentarios.