# Usar ORDS en APEX para acceder a los datos vía REST

Hace ya varios años que está disponible un componente de Oracle llamado [**Oracle REST Data Services**](https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/) que permite crear [servicios RESTful](https://restfulapi.net/) 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](https://restfulapi.net/http-methods/).

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*.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1698118121691/fe868c59-f99c-4c67-a3f6-b71b47bbe64d.png align="center")

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**.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1698118225030/8927a705-c1c1-4aa1-b8fc-020d126a9e70.png align="center")

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.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1698118508244/a86e0cdd-076e-4f44-b556-819c249dac8e.png align="center")

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.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1698118600013/e6ba58b0-4fe3-43cf-985c-065ca57aa4c3.png align="center")

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.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1698118974394/8579216e-4705-4432-8d3a-a2018afdbaf5.png align="center")

El siguiente paso es crear un [*module*](https://docs.oracle.com/en/database/oracle/apex/22.1/aeutl/about-oracle-RESTful-services-in-application-express.html#GUID-07A1A37A-7C8A-4C47-B849-7B178E74DA07), 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.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1698119313113/5da08689-4931-4b96-8aed-52d6dd612d3d.png align="center")

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.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1698119234253/0a32c637-12e4-4734-96b8-0416f0c9705a.png align="center")

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

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1698119459308/967a1127-9e66-4a19-b255-938043ded254.png align="center")

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.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1698119647083/406eb426-1ff1-496a-bdd9-65d5fb40b10d.png align="center")

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*](https://docs.oracle.com/en/database/oracle/apex/22.1/aeutl/about-oracle-RESTful-services-in-application-express.html#GUID-BCED781C-0DCB-4C10-96C0-BE38A7DF6BE5), 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.*

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1698120167092/45f3e1f6-8dd8-4e43-b188-acff2811a43d.png align="center")

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

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1698120285098/9d3178ea-732a-4bb6-b19d-e70ffd9fcaa7.png align="center")

Dado que mi servicio web accederá a la tabla de productos entonces así llamaré al [URI](https://es.wikipedia.org/wiki/Identificador_de_recursos_uniforme) del template (atención con la barra invertida al final). Terminamos la creación del *template* haciendo clic en el botón ***Create Template***.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1698120720814/8114d7c5-ddfe-4e15-8ca8-f95b10b8cd17.png align="center")

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*](https://docs.oracle.com/en/database/oracle/apex/22.1/aeutl/about-oracle-RESTful-services-in-application-express.html#GUID-B47DCA33-5607-43DD-8347-ADFCB121E887). Un poco más abajo en la misma pantalla encontraremos otra sección llamada ***Resource Handlers*** y haremos clic en ***Create Handler***.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1698120959618/e934a89b-8dc9-4a03-a42b-58819182dab0.png align="center")

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:

```sql
SELECT * FROM EBA_CUST_PRODUCTS
```

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1698121228629/484589ad-7f39-4794-82f6-70317568856d.png align="center")

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)

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1698122743065/62121395-ffa1-4542-bcc1-bca58d5495ff.png align="center")

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***.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1698121989819/4238e67c-fb9b-48c1-899c-5437431c16c0.png align="center")

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.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1698122110538/ea7374a0-fbe7-455c-a333-936340d1f286.png align="center")

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***.

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1698122239335/803cab41-a835-408c-b68a-d3f1a61cf8c7.png align="center")

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:

```sql
SELECT * FROM EBA_CUST_PRODUCTS WHERE ID = :id
```

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

![](https://cdn.hashnode.com/res/hashnode/image/upload/v1698122508508/3499c910-33ec-4b79-9e38-006715b6ad2e.png align="center")

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)