Hace ya varios años que está disponible un componente de Oracle llamado Oracle REST Data Services que permite crear servicios RESTful en la base de datos, con los cuales podemos acceder a los datos sin necesidad de tener un cliente Oracle instalado en el equipo, solo utilizando verbos HTTP.

En este pequeño tutorial les voy a mostrar cómo configurar ORDS en una instancia APEX en Oracle Cloud Infrastructure (OCI); el proceso es similar si tienen una instancia gratuita de APEX en apex.oracle.com o si tienen su propia instalación de APEX usando ORDS.

Lo primero que haré será instalar una de las aplicación de ejemplo que trae APEX en su galería, en mi caso instalaré la aplicación Customers.

Una vez instalada la aplicación y luego de ingresar al menos una vez para ejecutar el proceso de configuración de la aplicación, verificaremos en SQL Workshop todas las tablas que se crearon. En mi caso le daré una mirada a la tabla EBA_CUST_PRODUCTS.

En esta demostración crearé un servicio web que me permitirá consultar la lista de productos y también haré uno que me muestra el detalle de un producto dado su número de ID.

Procedemos a ir al menú SQL Workshop y seleccionamos RESTful Services. La primera vez que ingresemos nos mostrará una pantalla similar a la siguiente.

Aquí se nos indica que el esquema seleccionado no está registrado en la metadata de ORDS, simplemente debemos hacer clic en Register Schema with ORDS para continuar.

En el cuadro que se nos presenta podemos dejar los valores por defecto ya que esto es solo una prueba, sin embargo en sus ambientes de producción:

• Oracle recomienda cambiar el nombre del alias del schema para disminuir la posiblidad de que un atacante pueda determinar el nombre del usuario en la base de datos.

• Todas las opciones que permitan activar métodos de autorización deberían estar encendidos.

Presionamos Save Schema Attributes para guardar los cambios, inmediatamente se nos mostrará una pantalla similar a la siguiente.

El siguiente paso es crear un module, que no es más que un contenedor utilizado para agrupar diferentes servicios RESTful y que ademas sirve para definir la ruta base en el URL para acceder al servicio web.

En la imagen anterior vemos los componentes del URL para invocar el servicio web, la ruta base vendría después del alias del schema.

Procedamos entonces a ubicarnos en el árbol de la izquierda sobre la rama Modules y nos mostrará la siguiente pantalla.

Hagamos clic en el botón Create Module y nos solicitará los datos para la creación del módulo.

En este caso llamaremos al módulo "clientes" y su ruta base también será "clientes". Dejamos el resto de los campos con sus valores por defect y presionamos el botón Create Module. Al finalizar nos mostrará una pantalla como la siguente.

Ya podemos ver cómo queda el URL, pero aun faltan un par de pasos más.

El siguiente paso es la creación de un template, el cual define un servicio individual que puede ser llamado. Cada uno de estos templates luego tendrá definido uno más handlers, que serán los que manejarán cada una de las peticiones según el verbo HTTP utilizado.

Un poco más abajo en la pantalla de definición del módulo encontraremos la sección para definir el template.

En esta sección haremos clic en Create Template y nos mostrará una pantalla como la siguiente.

Dado que mi servicio web accederá a la tabla de productos entonces así llamaré al URI del template (atención con la barra invertida al final). Terminamos la creación del template haciendo clic en el botón Create Template.

Finalmente tenemos el URL completo para obtener la lista de productos, solo falta indicar la sentencia SQL que se ejecutará cuando hagamos un GET al URL, para esto crearemos un handler. Un poco más abajo en la misma pantalla encontraremos otra sección llamada Resource Handlers y haremos clic en Create Handler.

Se nos mostrará una nueva pantalla donde indicaremos las características. Dejaremos todos los campos por defecto y escribiremos la siguiente sentencia de búsqueda en la sección Source:

SELECT * FROM EBA_CUST_PRODUCTS

En este caso dejaremos la opción Source Type en Collection Query, ya que queremos devolver un conjunto de filas en formato JSON. Finalizamos presionando el botón Create Handler.

Una vez creado el handler, ya podemos empezar a probar el servicio web. Podemos usar cualquier navegador o aplicaciones especializadas como Postman (lo cual es lo recomendado, ya que no podremos hacer POST con el navegador fácilmente en caso de requerirlo)

En este caso nos devuelve un JSON que tiene una lista llamada "items" con un objeto que representa cada fila de la tabla.

Vemos ahora cómo crear un template para obtener los datos de un solo producto, enviando el ID del producto como parte del URI.

Hacemos clic sobre el módulo clientes y luego hacemos clic en el botón Create Template.

En este caso el URI varía un poco, ya que agregamos una variable de acoplamiento (o bind variable) que será sustituida por el ID del producto. Hacemos clic en Create Template para guardar.

Vean como el URL es ligeramente diferente, agregando el ID al final (en este caso no fue necesaria la barra invertida). Ahora crearemos un handler para manejar las solicitudes GET a este URL. Más abajo en esta misma pantalla haremos clic en Create Handler.

En este caso sí cambiaremos Source Type a la opción Collection Query Item, ya que solo recuperaremos un registro, y en la sección Source escribiremos la siguiente sentencia SQL:

SELECT * FROM EBA_CUST_PRODUCTS WHERE ID = :id

Finalizaremos presionando el botón Create Handler y procederemos a probar nuestro servicio web.

En este caso el servicio nos devuelve solo un objeto con todos los detalles del mismo. Por supuesto las sentencias SQL utilizadas pueden ser tan complejas como sea necesario para extraer la información necesaria, además de que es posible crear sentecias SQL que hagan UPDATE (usando PUT), INSERT (usando POST) y DELETE (usando DELETE)