A través del API Manager podemos crear nuestros propios webservices de tipo REST, SOAP o incluso Websocket. Además con el API Manager podremos gestionar el ciclo completo de estos webservices para ayudarnos en su gestión, políticas de acceso o incluso monetización. Pero otra de sus importantes características frente a otros productos similares es su extensibilidad y personalización.
Y debemos tener claro también, que el API Manager no está destinado a realizar lógica alguna. Es decir las APIs gestionadas deben estar asociadas a un backend o endpoint. Las cuales serán los encargados principales de realizar toda lógica asociada a estas APIs. Las cuales por sí sola no hacen o devuelven nada.
Y así debe ser en la mayoría de los casos. Aunque posteriormente, la realidad del entorno productivo siempre nos lleve a realizar soluciones out-of-the-box.
Conceptos y componentes en un API Manager
Para empezar debemos saber que un API Manager está dividido en diferentes componentes, y cada uno de ellos con una función muy definida. Entre todos crea un producto con múltiples características. Estos componentes son:
- Analytic: Motor de recolección y muestra de estadísticas.
- Publisher: Portal web del desarrollador de APIs.
- Store: Portal web del consumidor de APIs.
- Gateway: Procesador de peticiones y respuestas
- Key Manager: Gestor de claves de acceso
- Traffic Manager: Control de tráfico de peticiones.
Aunque podemos llevar a cabo la customización de muchos aspectos en el API Manager. Será concretamente dentro del Gateway donde podremos llevar a cabo la extensibilidad del API Manager o su customización, a la hora de invocar las APIs.
Esto es debido a que el Gateway el cual entra en juego en tiempo de ejecución, es en sí mismo un componente desarrollado a partir de una API del WSO2 ESB. El cual permitirá, como hemos dicho anteriormente, manejar todas las peticiones que se hagan al API Manager y aplicar diferentes políticas de uso. De forma autónoma en a través de llamadas a otros componentes. Como puede ser las reglas de control de tráfico, generación de estadísticas, control de tokens e intercepción de peticiones.
Extensibilidad
La extensibilidad, como ya hemos indicado, es una de las grandes características del API Manager, la capacidad para aumentar y personalizar sus ya de por sí amplias características. Para el caso que nos ocupa se nos ofrecen dos posibilidades: handlers y flujo de mediación (Mediation Flow). A continuación explicaremos que es cada uno.
- Handler: Al crear una API, se genera un fichero de configuración donde se incluyen todos los handlers asociados a dicha API. Este conjunto de handlers será ejecutado en el orden que indica el fichero cada vez que se invoque la API. Con los custom handlers podremos crear una lógica que se ejecute en cada una de las invocaciones de las APIs generadas.
- Mediation flow: Cada llamada al API Manager pasa por una secuencia de entrada, devuelve la respuesta a través de una secuencia de salida y en caso de error es tramitada por una secuencia de fallo. Debido a que las peticiones son gestionadas por el Gateway y su funcionamiento está basado en los Proxy services.
Estos componentes, como ya sabemos, son manejados por el Gateway que es el encargado de interceptar y gestionar las peticiones. Pero además debemos conocer cómo y en qué orden es invocados.
Como podemos ver, primero se ejecutarán los handlers, luego nuestras secuencias personalizadas y por último las secuencias por defecto.
Qué son los Handlers y qué acciones permiten realizar
Los handlers son interceptores de las peticiones que se realizan. Estos serán asociados a la API en el momento de su creación.
Cuando creamos una API generaremos un fichero, el cual será almacenado en la carpeta: <API-M_HOME>/repository/deployment/server/synapse-configs/default/api.
Si accedemos a un fichero de dicha carpeta podremos ver que tiene una composición idéntica a las de una API de un WSO2 EI. Y podremos ver cómo están asociados todos los handlers existentes en el momento de su creación.
Por defecto hay varios handlers que nos permiten realizar las siguientes acciones:
- Establecer las cabeceras HTTP de control de accesos (CORS).
- Control de autenticación.
- Control de límite de peticiones (throttling).
- Publicar latencias de las llamadas y respuestas o datos de uso de la API, siempre y cuando esté habilitado el Analytics.
- Realizar la llamada a las secuencias personalizadas si es que hay alguna configurada.
Este fichero tendrá una apariencia similar a:
<api xmlns="http://ws.apache.org/ns/synapse" name="admin--PizzaShackAPI"
context="/pizzashack/1.0.0" version="1.0.0" version-type="context">
<resource methods="DELETE PUT GET" uri-template="/order/{orderId}"
faultSequence="fault">
<inSequence>
<property name="api.ut.backendRequestTime"
expression="get-property('SYSTEM_TIME')"/>
<filter source="$ctx:AM_KEY_TYPE" regex="PRODUCTION">
<then>
<send><endpoint key="PizzaShackAPI--v1.0.0_APIproductionEndpoint"/><send>
</then>
<else>
<send><endpoint key="PizzaShackAPI--v1.0.0_APIsandboxEndpoint"/></send>
</else>
</filter>
</inSequence>
<outSequence>
<class name="org.wso2.carbon.apimgt.gateway.handlers.analytics.APIMgtResponseHandler"/>
<send/>
</outSequence>
</resource>
<handlers>
<handler class="org.wso2.carbon.apimgt.gateway.handlers.common.APIMgtLatencyStatsHandler"/>
<handler class="org.wso2.carbon.apimgt.gateway.handlers.security.CORSRequestHandler">
<property name="apiImplementationType" value="ENDPOINT"/>
</handler>
// ...
</handlers>
</api>
Tal y como hemos visto, podemos alterar el comportamiento de nuestra API creando secuencias personalizadas que realicen una lógica interna antes o después de la llamada al backend. Estas secuencias las podemos crear asociadas a una API concreta o de forma global a todas las APIs existentes.
Tipos de secuencias personalizadas
Si queremos crearlas con carácter individual, las podremos asociar a la hora de crear la API desde el portal web del Publisher. A través de este portal, podremos crear una API en tres sencillos pasos: diseño, implementación y gestión. Y será en el segundo paso, implementación, en el cual indicaremos los endpoints del backend y si queremos añadir una secuencia a ejecutar antes, después o en caso de error. Para ello debemos marcar el checkbox Enable Message Mediation y subir la secuencia que queramos asociar mediante los botones que aparecerán en pantalla.
Por defecto el API Manager también cuenta varias secuencias que están de libre disposición para los desarrolladores. Las cuales nos permitirán entre otras cosas:
- Validar el mensaje en formato JSON o XML.
- Logear un mensaje.
- Preservar la cabecera Accept.
- Pasar de XML a JSON o viceversa.
La configuración que acabamos de ver sólo es válida para la API específica en que se configure. El API Manager nos permite crear una secuencia genérica, de entrada y/o salida, que se ejecutará en todas las APIs de manera automática. Para ello debemos crear una secuencia con un nombre que siga el siguiente esquema: WSO2AM–Ext–<dirección>. La dirección es In o Out. Y añadirla a la carpeta del servidor:
<APIM_HOME>/repository/deployment/server/synapse-configs/default/sequences.
A Tener en cuenta dos cosas a la hora de crear los ficheros manualmente:
- El nombre del fichero no tiene porque coincidir con el nombre de la secuencia.
- La secuencia no se verá en el combo de selección del Publisher pero si se ejecutará.
Conclusión
API Manager nos permite a partir de distintas características aumentar la lógica asociada a nuestras APIs. En futuros posts, veremos ejemplos prácticos para llevar a cabo estas soluciones.
