Agregar fuentes REST en Oracle APEX

En una publicación pasada les mostraba como crear endpoints en la base de datos utilizando Oracle REST Data Services (ORDS), los cuales luego pueden ser usados en una aplicación APEX o consumidos desde cualquier aplicación que sea capaz de hacer peticiones REST. En esa oportunidad el origen de los datos era la misma base de datos ¿y si queremos consumir datos de una fuente REST que no sea nuestra base de datos? Hagamos un ejemplo extrayendo los datos de una API que está disponible de manera pública: Hyrule Compendium API; la cual tiene información sobre uno de mis juegos favoritos: The Legend of Zelda: Breath of the Wild.

Analizando la API

La primera tarea antes de hacer cualquier cosa en APEX es entender cómo la API nos devuelve la información que vamos a necesitar. Al revisar la documentación en su sitio web vemos que la API tiene de hecho dos componentes:

• Compendium API: Sirve la información sobre criaturas, equipos, materiales, monstruos y tesoros.

• Regions API: Provee información sobre las ocho regiones geográficas de Hyrule. El Compendium API tiene varios endpoints que devuelven diferentes tipos de datos. Veamos un par de ellos: Get all entries y Get Categories. Comencemos con Get all entries que parece ser el más sencillo dado que no utiliza ningún tipo de parámetro.

Get All Entries

El endpoint vendría siendo: /compendium/all y la forma de hacer la petición al API sería:

GET https://botw-compendium.herokuapp.com/api/v3/compendium/all

Hagamos una petición al endpoint para ver cómo sería la respuesta. En mi caso utilicé Insomnia pero pueden utilizar cualquier cliente para hacer la petición.

En este extracto podemos ver que la respuesta es un JSON que tiene un arreglo con el nombre data que tiene a su vez los objetos con diferentes categorías.

Get Categories

Este endpoint permite obtener la información de los objetos del juego según su categoría, la forma de hacer la petición al API sería la siguiente:

GET https://botw-compendium.herokuapp.com/api/v3/compendium/category/<category>

En este caso sí necesitamos enviar un parámetro en el URL que sería la categoría sobre la cual necesitamos la información. Para hacer una petición en Insomnia utilizaremos una variable que colocaremos en el URL.

Podemos ver que en este caso la respuesta también es un objeto que tiene un arreglo identificada como data que contiene los datos de los materiales para la categoría solicitada.

Veamos ahora como crear estas fuentes de datos REST en APEX.

Creando las fuentes de datos

Lo primero que haremos será crear una nueva aplicación, de momento solo la crearemos con la pantalla de Inicio ya que en un principio necesitamos acceso a los Shared Components. Este proceso lo pueden seguir desde cualquier instancia donde tenga APEX instalado. En mi caso utilizaré la que se encuentra en apex.oracle.com.

Desde la página inicial de APEX haremos clic en Create

Vamos a darle un nombre a la aplicación y hacemos clic en Create Application

Una vez en la aplicación ingresaremos a Shared Components

Un poco más abajo, en Data Sources seleccionaremos REST Data Sources

En esta sección lo que haremos será definir la forma en que APEX va a comunicarse con los servicios REST de los cuales queremos consumir la información. Luego sería posible utilizar estas fuentes para alimentar elementos como Interactive Reports o Interactive Grids.

Creando la fuente para Get All

Si no tenemos alguna otra fuente de datos veremos una pantalla similar a la siguiente:

Simplemente hagamos clic en Create para crear una nueva fuente de datos REST. Nos aparecerá la siguiente pantalla en la cual seleccionaremos From scratch (vamos a crear la fuente desde cero) y luego haremos clic en Next

En la siguiente pantalla veremos que nos solicita información básica sobre la fuente que vamos a crear, colocaremos la siguiente información:

• REST Data Source Type: Simple HTTP

• Name: Hyrule Compendium (o el nombre que ustedes quieran)

• URL Endpoint: https://botw-compendium.herokuapp.com/api/v3/compendium El resto de los campos podemos dejarlos en blanco, luego haremos clic en Next

En la siguiente pantalla se nos mostrará que APEX está creando un Remote Server que será la base desde la que crearemos el resto de las fuentes REST. Este es un paso que solo se realiza una vez. Dejaremos los datos tal como están y haremos clic en Next.

En la siguiente pantalla nos solicitará información sobre la paginación de la fuente, seleccionaremos No Pagination y haremos clic en Next

La siguiente pantalla nos solicitará que le indiquemos cómo se hará la autenticación con la fuente de datos, en este caso este servicio no requiere autenticación, por lo que lo dejamos tal como está y hacemos clic en Advanced.

Dado que el servicio devuelve un JSON que no está construido específicamente para ser leído por APEX, vamos a ayudarlo a entender su estructura mediante un archivo de respuesta de ejemplo. Desde la aplicación que estén utilizando para evaluar el API, exporten la respuesta luego de haber hecho la solicitud a All Entries y guárdenlo en un archivo de texto.

Volviendo a APEX, en la pantalla Parameters modificaremos dos opciones:

• Discovery Sample: Allí cargaremos el archivo que exportamos en el paso anterior

• Row Selector: Le indicaremos la clave dentro del archivo que identifica a la tabla de datos. Recuerden que toda la información está en un arreglo llamado data que a su vez es un arreglo de objetos.

Finalmente hagamos clic en Discover para verificar que puede leer correctamente el API.

En este caso vemos que leyó correctamente el API y fue capaz de identificar el arreglo en el cual se guarda la información. Para finalizar hacemos clic en Create REST Data Source.

Si hacemos clic en el nombre de la fuente podremos ver la información con la que fue creado, así como también tendremos la posibilidad de agregar otras instrucciones REST (como PUT o POST) si el API lo permitiese.

Creando la fuente para Get Category

Vamos ahora a crear la fuente REST para Get Category, este es un poco diferente ya que debemos pasar un parámetro en el URL en el cual le indicamos la categoría que deseamos consultar.

Volvemos a la pantalla donde tenemos la lista de fuentes REST y hacemos clic en Create para crear uno nuevo

En la siguiente pantalla seleccionaremos From scratch y luego hacemos clic en Next hasta llegar a la pantalla donde indicaremos el URL del servicio. Introducimos una descripción y el URL y hacemos clic en Next

Como el servidor remoto fue creado cuando registramos la primera fuente entonces APEX nos mostrará la información existente. Lo dejamos como está y hacemos clic en Next

En la siguiente página nos solicitará la información sobre paginación, hacemos clic en Next sin hacer cambios.

En la siguiente página nos solicitará información sobre el método de autenticación del servicio, lo dejamos desactivado ya que no requiere autenticación y hacemos clic en Advanced.

Esta solicitud es un poco diferente a la anterior ya que requiere que pasemos un parámetro en el URL el cual le indica cuál es la categoría que vamos a consultar. Así que vamos a colocar esa información en la pantalla de parámetros. Al igual que con el caso anterior, vamos a descargar un archivo de respuesta JSON de ejemplo para que APEX pueda crear fácilmente la fuente.

Finalmente hacemos clic en Discover para verificar que la fuente funciona correctamente. Si todo está bien deberíamos ver esta pantalla.

Finalmente hacemos clic en Create REST Data Source.

Ahora podemos utilizar estas fuentes de datos en nuestras aplicaciones en cualquier elemento que permita que la fuente de datos sea un REST Data Source, como por ejemplo un Reporte Interactivo

Recuerden de asegurarse que están pasando los parámetros correctos y obtendrán un reporte como este:

Espero que les sea de utilidad.