En la actualidad cada vez son más las compañías que se incorporan al proceso de Transformación Digital, tratando de exponer sus recursos empresariales a terceros, con el fin de potenciar las relaciones con partners y clientes. La publicación de APIs fuera  del  entorno corporativo permite monetizar por diferentes vías los activos de negocio pero también pone en peligro la imagen y seguridad de la compañía en el caso de que la gestión de estas APIs no se realice de manera adecuada.

Adoptar una solución de API Management nos va a permitir cubrir las necesidades comunes de todas las APIs de una manera global liberando al desarrollador de este tipo de tareas.

En este post vamos a trabajar con la herramienta API Manager de WSO2 (AM), con la que realizaremos una gestión adecuada de nuestras APIs permitiéndonos catalogarlas y publicarlas como si de un producto se tratase.

WSO2 API Manager

Como hemos comentado anteriormente, se trata de la solución de la suite WSO2 para diseñar y publicar APIs, como el resto de productos de este fabricante es Open Source y está basado en proyectos de la Apache Software Foundation.

La última versión productiva publicada es la 1.10.0 aunque la beta de la versión 2.0.0 también está disponible para descargar en la página oficial.

Para la publicación de estadísticas tradicionalmente ha sido necesaria la integración de WSO2 API Manager con otros productos de la suite, en la siguiente tabla mostramos la matriz de compatibilidad de este tipo de integraciones:

Los cambios que se han ido reflejando, con el paso del tiempo, en esta matriz de compatibilidad han sido los siguientes:

1. Hasta la versión 1.9.0 de API Manager era necesaria la integración con WSO2 BAM (Business Analytics Monitor) para la publicación de estadísticas. En la vesión 1.9.1 se podía elegir la integración con WSO2 BAM o con WSO2 DAS (Data Analytics Server) y en la versión 1.10.0 y en la beta de la versión 2.0.0 sólo es posible publicar estadísticas mediante WSO2 DAS.
   Es importante destacar que WSO2 DAS 3.0.0 nació como una evolución de WSO2 BAM 2.5.0.
2. Hasta la versión 1.9.1 de API Manager era necesaria la implantación de una base de datos intermedia entre el propio API Manager y BAM o DAS pero desde la versión 1.10.0 es posible evitar esta base de datos y utilizar el cliente REST de API Manager para recuperar la información directamente de DAS. Este cliente REST aporta un mejor rendimiento que la base de datos intermedia.

En este post utilizaremos la última versión estable de WSO2 AM (1.10.0) y de WSO2 DAS (3.0.1).

Instalación, Configuración y Arranque

Descargamos la versión 1.10.0 de WSO2 AM y descomprimimos el archivo en el directorio que seleccionemos, en nuestro caso /opt. Realizamos la misma operación con la versión 3.0.1 de WSO2 DAS.

Modificamos el puerto de escucha de WSO2 DAS para evitar que choque con el de AM ya que ambos van a correr en la misma máquina, para ello mofificamos la propiedad 'Offset' de su archivo carbon.xml que en nuestra instalación tenemos ubicado en /opt/wso2das-3.0.1/respository/conf.

<Ports>

 <!-- Ports offset. This entry will set the value of the ports defined below to define value + Offset.
e.g. Offset=2 and HTTPS port=9443 will set the effective HTTPS port to 9445 -->

  <Offset>2</Offset>
...

En este momento tenemos configurado API Manager para que arranque la consola de administración en el puerto 9443 y Data Analytics Server para que lo haga en el 9445.

Iniciamos AM mediante el script de arranque ubicando en /opt/wso2am-1.10.0/bin

[wso2user@Centos7WSO2 bin]$ ./wso2server.sh
JAVA_HOME environment variable is set to /opt/jdk1.7.0_79  
CARBON_HOME environment variable is set to /opt/wso2am-1.10.0  
Using Java memory options: -Xms256m -Xmx1024m -XX:MaxPermSize=256m  
[2016-06-09 10:13:31,654]  INFO - CarbonCoreActivator Starting WSO2 Carbon...
[2016-06-09 10:13:31,662]  INFO - CarbonCoreActivator Operating System : Linux 3.10.0-327.el7.x86_64, amd64
[2016-06-09 10:13:31,662]  INFO - CarbonCoreActivator Java Home        : /opt/jdk1.7.0_79/jre
[2016-06-09 10:13:31,663]  INFO - CarbonCoreActivator Java Version     : 1.7.0_79
[2016-06-09 10:13:31,663]  INFO - CarbonCoreActivator Java VM          : Java HotSpot(TM) 64-Bit Server VM 24.79-b02,Oracle Corporation
[2016-06-09 10:13:31,663]  INFO - CarbonCoreActivator Carbon Home      : /opt/wso2am-1.10.0
[2016-06-09 10:13:31,663]  INFO - CarbonCoreActivator Java Temp Dir    : /opt/wso2am-1.10.0/tmp
[2016-06-09 10:13:31,663]  INFO - CarbonCoreActivator User             : wso2user, en-US, Europe/Madrid
...
[2016-06-09 10:14:48,170]  INFO - StartupFinalizerServiceComponent Server           :  WSO2 API Manager-1.10.0
[2016-06-09 10:14:48,171]  INFO - StartupFinalizerServiceComponent WSO2 Carbon started in 85 sec
[2016-06-09 10:14:48,972]  INFO - CarbonUIServiceComponent Mgt Console URL  : https://192.168.122.1:9443/carbon/
[2016-06-09 10:14:48,972]  INFO - CarbonUIServiceComponent API Publisher Default Context : http://192.168.122.1:9763/publisher
[2016-06-09 10:14:48,972]  INFO - CarbonUIServiceComponent API Store Default Context : http://192.168.122.1:9763/store

Como nos indica el log tenemos accesibles tres consolas:

1. Consola de administración general: https://192.168.122.1:9443/carbon/
2. Consola de publicación: http://192.168.122.1:9763/publisher
3. Consola API Store:  http://192.168.122.1:9763/store

Iniciamos DAS mediante el script de arranque ubicando en /opt/wso2das-3.0.1/bin:

[wso2user@Centos7WSO2 bin]$ ./wso2server.sh
JAVA_HOME environment variable is set to /opt/jdk1.7.0_79  
CARBON_HOME environment variable is set to /opt/wso2das-3.0.1  
Loading spark environment variables  
[2016-06-09 10:18:57,976]  INFO {org.wso2.carbon.core.internal.CarbonCoreActivator} -  Starting WSO2 Carbon...
[2016-06-09 10:18:57,977]  INFO {org.wso2.carbon.core.internal.CarbonCoreActivator} -  Operating System : Linux 3.10.0-327.el7.x86_64, amd64
[2016-06-09 10:18:57,977]  INFO {org.wso2.carbon.core.internal.CarbonCoreActivator} -  Java Home        : /opt/jdk1.7.0_79/jre
[2016-06-09 10:18:57,977]  INFO {org.wso2.carbon.core.internal.CarbonCoreActivator} -  Java Version     : 1.7.0_79
[2016-06-09 10:18:57,977]  INFO {org.wso2.carbon.core.internal.CarbonCoreActivator} -  Java VM          : Java HotSpot(TM) 64-Bit Server VM 24.79-b02,Oracle Corporation
[2016-06-09 10:18:57,978]  INFO {org.wso2.carbon.core.internal.CarbonCoreActivator} -  Carbon Home      : /opt/wso2das-3.0.1
[2016-06-09 10:18:57,978]  INFO {org.wso2.carbon.core.internal.CarbonCoreActivator} -  Java Temp Dir    : /opt/wso2das-3.0.1/tmp
[2016-06-09 10:18:57,978]  INFO {org.wso2.carbon.core.internal.CarbonCoreActivator} -  User             : wso2user, en-US, Europe/Madrid
...
[2016-06-09 10:20:05,703]  INFO {org.wso2.carbon.core.internal.StartupFinalizerServiceComponent} -  Server           :  WSO2 Data Analytics Server-3.0.1
[2016-06-09 10:20:05,741]  INFO {org.wso2.carbon.core.internal.StartupFinalizerServiceComponent} -  WSO2 Carbon started in 75 sec
[2016-06-09 10:20:06,628]  INFO {org.wso2.carbon.ui.internal.CarbonUIServiceComponent} -  Mgt Console URL  : https://192.168.122.1:9445/carbon/

La consola de administración de DAS está ahora disponible en: https://192.168.122.1:9445/carbon/

Creación de Roles y Usuarios

Para poder trabajar correctamente con API Manager vamos a utilizar diferentes usuarios asociados a diferentes roles. La tabla siguiente indica los usuarios que vamos a necesitar:

Para la creación de los roles accedemos a la consola de adminstración de API Manager con el usuario 'admin', con la contraseña por defecto 'admin', y en la sección 'Main' añadimos el nuevo rol 'API_Provider'.

Le asignamos al rol los permisos de Governance, Login, Manage/API/Create y Manage/Govern:

De la misma forma creamos el rol 'API_Publisher'.

Los permisos para este rol son Login y Manage/API/Publish.

El rol 'subscriber' viene creado de manera predefinida en el producto por lo que no tenemos que generarlo. El listado de roles existentes en este momento quedaría de la siguiente forma:

A continuación y en la misma sección de la consola vamos a crear los usuarios asociados a los roles recién generados. Comenzamos por el usuario 'proveedor'.

Y lo asociamos al rol 'API_Provider'.

Creamos también el usuario 'publicador'.

Y lo asociamos a su rol correspondiente.

El último usuario que vamos a crear es 'suscriptor'.

Y lo asociamos al rol predefinido 'subscriber'.

El listado final de usuarios disponibles es el siguiente:

Creación del API

Para generar el primer API en WSO2 AM nos vamos a identificar en la consola Publisher con el usuario 'proveedor' y en la sección My APIs seleccionaremos la opción 'New API...'

Para este post vamos a importar una definición de API basada en Swagger 2.0, en concreto vamos a utilizar la clásica Petstore. Cabe destacar que tenemos también las opciones de crear un API a partir de un WSDL de un servicio SOAP o de diseñar desde cero un nuevo API utilizando la interfaz gráfica.

Completamos el diseño del API indicando el nombre que le vamos a dar, el contexto sobre el cual se va   levantar, la versión que va a ser del API, la visibilidad sobre los roles existentes, una fotografía que será el icono asociado al API (en este caso y al tratarse de una tienda de mascotas va a ser una instantánea de mi simpática cobaya Amy), una descripción de la funcionalidad que ofrece y una serie de tags para poder clasificarla. En este punto es posible también modificar y/o ampliar los recursos y métodos incluidos en la definición importada del API.

Una vez completada la fase de diseño pasamos a la de implementación, en esta fase decidimos si vamos a trabajar con un API cuya implementación esté fuera del ámbito de API Manager (Managed API) o por el contrario si vamos a crear un prototipo ejecutable del API en el propio API Manager (Prototyped API). En este post vamos a gestionar un API productivo desplegado fuera del ámbito del API Manager ya que es el caso de uso que queremos cubrir.

En la sección de  implementación del API en WSO2 AM vamos a indicar el endpoint de acceso a la petstore de Swagger y lo vamos a catalogar como endpoint productivo. Para este caso no vamos a crear un endpoint de tipo sandbox pero cabe destacar que podríamos hacerlo si necesitaramos un entorno de tip preproductivo.

Los endpoints los podemos validar mediante la opción 'Test' y también podemos realizar una configuración mas detallada de los mismos, pudiendo indicar códigos de error que al ser recibidos suspenden temporalmente el endpoint, gestión de reintentos en caso de errores de timeout y ejecución de secuencias (originales de ESB) en caso de error.

Es posible también indicar el nivel de seguridad asociado al endpoint, activar el tracking de mensajes sobre el mismo para habilitación de algunas estadísticas que veremos posteriormente y asociar secuencias de entrada y salida que se ejecutarán en cada petición enrutada al propio endpoint.

Tras completar las secciones de diseño e implementación vamos a configurar el módulo de gestión del API. En esta fase vamos a indicar si la versión del API que estamos creando va a ser la versión por defecto, vamos a indicar la disponibilidad del API en función de los niveles de posible suscripción que hayamos configurado, los transportes soportados para recibir peticiones, la activación del hard throttling, la posibilidad de cachear respuestas y la información de contacto. Es posible también definir una agrupación de APIs delimitada por roles.

Y, en este momento, ya tendríamos nuestra API creada y preparada para ser expuesta..

Publicación del API

El siguiente paso que vamos a dar va a ser publicar nuestra API para hacerla visible a los futuros consumidores, para ello vamos a acceder a la consola Publisher con el usuario 'publicador'. Una vez identificados correctamente seleccionamos nuestra recién creada Petstore en su versión 1.0.0 y en la pestaña Lifecycle indicamos 'Publish'.

Una vez realizada la publicación, podemos observar el resto de opciones que podemos seleccionar para modificar el estado actual del API dentro de su ciclo de vida:

Suscripción al API

Una vez publicada la API ya puede empezar a ser consumida, para ello es necesario realizar una suscripción a la misma, esta suscripción se ha de realizar desde la API Store y podría requerir una aprobación manual. El registro en API Store lo realizamos con el usuario suscriptor y nada mas acceder a la consola vemos la notificación que nuestra que la API PetStore ha sido publicada recientemente.

Si accedemos al detalle del API podemos observar toda su información clasificada en diferentes pestañas, también tenemos la opción de realizar la suscripción. La suscripción tiene que estar asociada a una aplicación, en este caso vamos a utilizar la aplicación por defecto. Se puede decir que una aplicación es una agrupación de APIs, con un denominador común, a las que un usuario está suscrito.

Una vez suscritos al API podemos consultar las claves de cliente (Consumer Key y Consumer Secret) y el token de acceso temporal generado a partir de las mismas. Este token se utilizará para identificar las peticiones realizadas por cada usuario. El token tiene una validez delimitada configurable y puede ser renovado mediante invocaciones REST al API públicado por WSO2 AM o desde la propia consola.

En la pestaña API Console se pueden realizar peticiones de prueba para ver las respuestas del API:

Si al intentar atacar al API vía HTTPS desde la API Store o desde un cliente externo como Postman obtenemos un error de confianza de certificado (explicado en https://wso2.org/jira/browse/APIMANAGER-4268) podemos forzar su aceptación indicando en el navegador la URL local de nuestra máquina con el puerto seguro, en nuestro caso https://192.168.1.122:8243 y añadiendo la excepción de seguridad.

Estadísticas

Si volvemos a la consola API Publisher y nos identificamos como el usuario 'proveedor' e intentamos consultar las estadíticas de nuestra API observamos que estas están deshabilitadas.

Esto es debido a que todavía no hemos configurado las comunicaciones entre WSO2 AM y WSO2 DAS. Como ya hemos comentado, en versiones anteriores era necesaria la utilización de una base de datos intermedia para compartir la información, pero en esta última versión ya es posible utilizar el cliente REST de API Manager que nos va a permitir realizar una configuración mas rápida y un acceso a los datos con un mejor rendimiento.

Para realizar este proceso vamos a acceder a una consola que no habíamos visto aún, se trata de la consola de gestión de analíticas de API Manager que podemos encontrar en el mismo puerto que el resto de consolas, en nuestro caso en https://localhost:9443/admin-dashboard/Analytics. Nos identificamos con el usuario 'admin' de nuevo.

En esta consola vamos a habilitar la publicación de estadísticas y a indicar la configuración necesaria para establecer las comunicaciones entre ambos productos. Los parámetros a configurar son la URL del Event Receiver del AM con el puerto por defecto (añadir URL Group) y la URL del Event Analyzer del DAS con el puerto por defecto mas el offset que hemos indicado en carbon.xml, en nuestro caso el offset es 2.

En esta consola también podríamos crear y modificar los niveles de suscripción disponibles. En este post no realizaremos ningún cambio en esta configuración.

A partir de este momento se podrían empezar a consultar las estadísticas de las APIs publicadas desde la consola API Publisher como indica el nuevo mensaje que aparece en la sección de estadísticas.

Ahora vamos a generar algo de tráfico, en este caso lanzando peticiones desde Postman para crear llamadas externas al API Manager y simular su funcionamiento real. Indicamos en la cabecera 'Authorization' el bearer token vigente.

Una vez procesadas las peticiones anteriores podemos ver las estadísticas de uso del API referentes a las mismas.

Estas estadísticas son visibles desde la parte publicadora, pero el cliente también puede consultar sus estadísticas propias.

Consulta de estadísticas vía API REST

Como hemos observado, WSO2 API Manager ofrece una serie de dashboards con información relativa a las estadísticas de consumo de las APIs gestionadas, pero si necesitamos obtener esta información de manera más personalizada o si necesitamos consumirla desde otro sistema podemos optar por utilizar el DAS REST API. Las consultas mediante el API REST están basadas en la sintaxis de búsqueda de Apache Lucene. En la documentación oficial se pueden consultar todas las funciones que cubre el API para poder ver hasta donde podemos llegar consultando las estadísticas.

A continuación vamos a ver un par de ejemplos de este tipo de consultas. Vamos a empezar por realizar una consulta sobre la tabla API REQUEST SUMMARY que nos va a devolver la información relativa a las consultas que se han hecho a las APIs. Como anteriomente utilizamos Postman:

También podemos preguntar por estadísticas de respuesta de las APIs (Nótese que el token de autorización es diferente porque ha caducado y lo hemos regenerado).

También se pueden realizar operaciones de agregación mediante la utilización del recurso aggregates y el método POST. En este caso obtenemos la suma de todas las peticiones en un intervalo de tiempo en formato Long.

Aunque queda fuera del alcance de este post me gustaría comentar brevemente que existe la posibilidad de crear tablas temporales personalizadas para almacenar información particular del uso de las APIs. Estas tablas posteriormente podrán ser consultadas por peticiones REST de tipo Lucene, recurso aggregates, para obtener estadísticas customizadas.

La flexibilidad a la hora de obtener información estadística nos permite afinar, aumentando la complejidad de las consultas, hasta obtener el dato estadístico deseado. De esta manera se facilita la integración con herramientas de facturación que nos permitan monetizar las APIs.

Conclusión

A lo largo de este post hemos ido descubriendo un subconjunto de las funcionalidades principales de WSO2 API Manager, gracias a ellas podemos hacernos una primera idea de qué nos puede aportar la herramienta y cómo podemos exponer nuestras APIs de una manera segura y controlada.

Siempre que ofrezcamos funcionalidad a terceros nos va a interesar saber cómo ésta es consumida, si utilizamos una solución de API Management tendremos gran parte del camino recorrido.

¡Síguenos en Twitter para no perderte ni un post!