La gran mayoría de las aplicaciones hoy en día de una u otra manera terminan consumiendo servicios web, es por ello que es muy grato saber que Apex nos provee todo lo necesario para poder consumir servicios web ya sea internos desde nuestra base de datos como también servicios web externos a nuestra aplicación.
Todas las grandes compañías ofrecen servicios web como Facebook, Flickr, YouTube, LinkedIn y muchas más, y a medida que más y más aplicaciones tienden a interconectarse con todos estos servicios, es necesario que podamos aprovechar todas estas funcionalidades para enriquecer nuestras aplicaciones y sin duda para eso necesitamos conocer cómo “consumir” o “producir” RESTful Web Services. Para la fortuna de todos, Apex 5.0 tiene una manera simple y directa de consumir Servicios Web.
En este artículo quiero compartir con todos lo que aprendí al tener que utilizar un recurso web externo en mi aplicación en Apex.
El ejemplo que veremos a continuación se basa en un servicio web externo y como con Apex podemos consumir los datos desde el archivo XML.
Lo primero que necesitamos tener en cuenta es cuál es el servicio web que vamos a utilizar.
Identificar el servicio Web que deseamos utilizar
Para este ejemplo vamos a utilizar el servicio web que nos provee la “Federal Aviation Administration” del Departamento de Transporte de Estados Unidos.
http://services.faa.gov/docs/services/airport/
Este Servicio obtiene el estado del aeropuerto para cualquier aeropuerto importante, incluyendo demoras conocidas y datos meteorológicos del NOAA. (National Oceanic and Atmospheric Administration)
Para utilizar un servicio web necesitamos de primera instancia conocer la URI. Un URI (Uniform Resource Identifier) que en español es un Identificador Uniforme de Recursos, sirve para identificar recursos en Internet. La URL es simplemente un subgrupo dentro de la URI.
El Servicio web nos provee de la siguiente información:
URI: http://services.faa.gov/airport/status/airportCode
Método HTTP:
GET
Parámetros:
Todos los siguientes parámetros son requeridos:
airportCode. Requerido. Es necesario ingresar el código del aeropuerto de tres letras para recuperar los datos y mostrarlos en la aplicación, por ejemplo, “SFO” que representa el aeropuerto “San Francisco International”
Ejemplo de Solicitud XML:
http://services.faa.gov/airport/status/SFO?format=application/xml
Cuando ingresamos la URI en nuestro navegador podemos ver el resultado del servicio web en formato XML y en base a dicha visualización podemos determinar qué datos vamos a mostrar en nuestra aplicación. Claro que lo más importante es que cuando consumimos servicios web estudiemos bien la API del servicio ya que allí podemos encontrar la información de los parámetros requeridos y los opcionales.
En la imagen de abajo, (resaltado con flechas naranjas), definimos los datos que vamos a mostrar en la aplicación.
Datos que consumiremos: Delay, IATA, State, Name, Visibility, Weather, Temp, Wind, City.
Como podemos ver en el URI de ejemplo:
http://services.faa.gov/airport/status/SFO?format=application/xml
SFO representa el parámetro airportCode y necesitamos además indicar qué tipo de formato será usado, en este caso el tipo es xml, por ello vamos a tener otro parámetro llamado Format que utilizaremos como parámetros de entrada en nuestra aplicación para solicitar el servicio web.
Crear Aplicación de Escritorio en Blanco
Ahora es momento de pasar a Apex y crear una Aplicación en blanco de tipo Escritorio, la llamaremos RESTful Services Demo.
Está de más decir, pero para trabajar con Servicios Web, debemos tenerlo habilitado en nuestra aplicación.
Crear Referencias de Servicios Web
Desde la página de inicio de la aplicación RESTful Services Demo recién creada nos dirigimos a Componentes Compartidos.
En la sección Referencias de Datos hacemos clic en Referencias de Servicios Web.
Para crear una nueva Referencia de Servicio Web, hacemos clic en el botón Crear >
Se inicia el asistente para crear la Referencia de Servicio Web.
Seleccionamos REST y hacemos clic en el botón Siguiente >
En Detalles de REST ingresamos los siguientes Datos:
Nombre: AirportStatus
URL: http://services.faa.gov/airport/status
Proxy: http://www-proxy.us.oracle.com
Método HTTP: GET
Autenticación Básica: No
No agregamos ninguna cabecera
Hacemos clic en el botón Siguiente >
En Entradas REST vamos a añadir los dos parámetros que necesitamos para realizar la solicitud.
AirportCode: Cadena
Format: Cadena
Hacemos clic en el botón Siguiente >
En Salidas REST configuramos los siguientes datos:
- Formato de Salida: XML
- XPath a Parámetros de Salida: /AirportStatus
Es muy importante conocer el XPath a Parámetros de Salida, si observamos la salida XML de ejemplo podemos ver que la primer etiqueta se llama AirportStatus y luego se desprenden las demás etiquetas en jerarquía hacia abajo, el cual nos indica donde está el dato a consumir en el archivo XML, como vamos a mostrar datos de distintas partes del XML usaremos la primer etiqueta para que sea nuestro punto de partida del XPath.
- Parámetros de Salida REST
| Nombre | Ruta de Acceso | Tipo |
| State | /State | Cadena |
| City | /City | Cadena |
| Name | /Name | Cadena |
| IATA | /IATA | Cadena |
| Temp | /Weather/Temp | Cadena |
| Weather | /Weather/Weather | Cadena |
| Visibility | /Weather/Visibility | Cadena |
| Wind | /Weather/Wind | Cadena |
| Delay | /Delay | Cadena |
Hacemos clic en el botón Crear
Podemos visualizar que se ha creado una nueva referencia de Servicio Web.
Probar El Servicio Web
Podemos probar la referencia haciendo clic en el botón de “play”
Ingresamos los Parámetros de Entrada:
AirportCode: SFO
Format: Application/xml
Y hacemos clic en el botón Probar
En la ficha Respuesta podemos ver la salida del archivo XML.
Crear Página Pantalla e Informe Basados en Servicio Web
Desde la página de Inicio de la Aplicación hacemos clic en el botón Crear Página >
Interfaz de usuario: Escritorio
Seleccione un Tipo de Página: Pantalla — Pantalla e Informe Basados en Servicio Web.
- En el paso “Seleccionar Servicio y Operación”
- Referencia de Servicio Web: AirportStatus
- Tipo de Referencia de Servicio Web: RESTful
- Operación: doREST
- Hacemos clic en el botón Siguiente
- En el paso “Atributos de Página y de Región”
- Aceptamos los valores por defecto y hacemos clic en el botón Siguiente
- En el paso “Elementos de Entrada”
- Nombre del Elemento: P2_AIRPORTCODE — Crear: Sí
- Nombre del Elemento: P2_FORMAT — Crear: Sí
- Hacemos clic en el botón Siguiente
- En el paso “Parámetros del Informe”
- Seleccionamos y tildamos todos los parámetros del Informe
- Hacemos clic en el botón Siguiente
- Seleccionamos y tildamos todos los parámetros del Informe
- En el paso “Menú de Navegación”
- Preferencia de Navegación: Crear nueva entrada del menú de navegación
- Nueva Entrada del Menú de Navegación: RESTful Services Demo
- Entrada de Menú de Navegación Principal: Seleccionado Inicio
- Hacemos clic en el botón Siguiente
- En el paso “Confirmar”
- Verificamos los datos y hacemos clic en el botón Crear
Ejecutar la Aplicación
Desde la página de Inicio de la Aplicación hacemos clic en el icono “Ejecutar Aplicación”
Iniciamos la sesión ingresando nuestras credenciales y accedemos a la Página “RESTful Services Demo”
Es el momento de probar el consumo del Servicio Web que creamos, para ello ingresamos los siguientes parámetros de entrada:
Airportcode: SNA
Format: Application/xml
Hacemos clic en el botón Ejecutar
Como podemos ver, Apex nos facilita en gran medida el consumo de Servicios Web externos para ser utilizados en nuestras aplicaciones web.
Ejemplo Archivo XML con atributos
Antes de terminar sólo quiero mostrar otro ejemplo de archivo XML el cual dentro de las etiquetas que representan los elementos del archivo XML podemos tener atributos que nos dan información adicional sobre el elemento por medio del valor que llevan asociado.
Tenemos esta URI para el consumo de Servicios Web:
http://api.openweathermap.org/data/2.5/weather?q=London&mode=xml
Que tiene dos parámetros:
q = Ciudad
mode = xml
El Archivo XML se muestra de la siguiente forma:
Como podemos observar la estructura del archivo es diferente a la que vimos en el primer ejemplo.
Cuando estamos configurando la Referencia del Servicio Web en los Parámetros de Salida debemos ingresar la Ruta de Acceso, y en el caso de que el elemento contenga atributos varía la forma que en se representa el acceso a los datos, agregando la @ antes del nombre del atributo.
Por ejemplo para mostrar los parámetros de Salida de País, Temperatura, Temperatura Mínima, Temperatura Máxima, Longitud, Latitud y Velocidad del Viento, debemos configurarlos de la siguiente manera:
| Nombre | Ruta de Acceso | Tipo |
| País | /city/country | Cadena |
| Temperatura | /temerature/@value | Cadena |
| Temp Min | /temerature/@min | Cadena |
| Temp Max | /temerature/@max | Cadena |
| Longitud | /city/coord./@lon | Cadena |
| Latitud | /city/coord./@lat | Cadena |
| Velocidad del Viento | /wind/speed/@value | Cadena |
De esta forma podemos consumir los datos desde Apex según la estructura del Archivo XML.
Conclusión
Finalmente, según mi opinión, lo más más importante en este caso es identificar el servicio web externo que vamos a usar e identificar la URI con sus respectivos parámetros de entrada requeridos porque el resto como pudimos observar es muy simple de configurar, gracias a los asistentes que nos provee Apex.
Hemos aprendido en este artículo a:
- Identificar el Servicio Web que deseamos utilizar
- Crear una Referencia de Servicio Web en Apex
- Crear una Página del tipo Pantalla e Informe Basados en Servicio Web
- Consumir Servicios Web RESTful Externos