Cómo configurar Postman para usar las Platform APIs de AnyPoint

Postman se ha convertido en los últimos años en la herramienta standard para cualquier desarrollador de APIs. Nos proporciona una interfaz intuitiva y sencilla para interactuar y probar APIs en general. Y, en particular, para nuestro trabajo con Mule hay dos escenarios donde Postman nos es muy útil.

El primero, obviamente, como herramienta de testing. Una vez construidas nuestras Mule APIs podemos usar Postman para probar las distintas operaciones de nuestras APIs: GET, POST, PUT..., podemos construir nuestro JSON para las request e incluso podemos hacer nuestras pruebas con distintos métodos de autenticación en las APIs, por poner varios ejemplos.
El otro caso de uso, para el que Postman nos es muy util como desarrolladores Mule, es para interactuar con las Platform APIs de Anypoint.

Para los que no las conozcáis, las AnyPoint Platform APIs son el conjunto de APIs que MuleSoft pone a disposición para interactuar con todas las funcionalidades de AnyPoint Platform de forma programática. Prácticamente todas las acciones que llevamos a cabo en AnyPoint mediante la interfaz gráfica se pueden hacer mediante una llamada a una de estas Platform APIs. Este conjunto de APIs, como no podia ser de otra forma, están publicadas en el Developer Portal de MuleSoft.

Este catálogo está dividido en varias APIs correspondientes a los distintos módulos de AnyPoint: Design Center, API Manager, Runtime Manager, Exchange... y dentro de cada API del catálogo encontraréis documentación, ejemplos, la lista de operaciones y, también, una consola para probar directamente cada operación. Con esta consola nos podría bastar para construir nuestras requests y ver las responses, pero con Postman podemos sacarle mucho más partido.

Fundamentalmente usando las Collections y Environments de Postman. Las Collections es la funcionalidad de Postman que nos permite guardar las distintas requests que construimos y agruparlas. De esta forma podemos repetir las requests a Platform APIs sin tener que recordarnos de introducir cada vez los distintos parámetros o objetos de entrada de cada request y, sobre todo, sin tener que recordar el endpoint al que llamamos.

Y, con los Environments, lo que conseguimos es parametrizar. En lugar de guardar nuestras requests con los valores hardcoded para nuestros user, password, Org Id... podemos definir nuestro Entorno con todos esos parámetros y sus valores para nuestra Anypoint Org, de manera que las requests que tenemos guardadas hacen referencia a estos parámetros. Con esto además conseguimos que cambiar de una org a otra no nos cueste nada; en lugar de cambiar los valores de todas las requests solo tenemos que cambiar de Entorno.

Veamos a continuación cómo preparar nuestro Workspace en Postman para interactuar y sacarle el máximo partido a nuestras Platform APIs en dos pasos:

1. Setup Inicial

Lo primero que vamos a hacer es crear nuestro Environment y automatizar el proceso de Login en AnyPoint mediante los siguientes pasos:

Crear nuestro Entorno

Para ello, en la parte superior de nuestra consola Postman haremos click en New y a continuación Environment. Si todavía andas un poco perdido con Postman aquí puedes ver cómo crear Entornos en Postman y definir vuestras variables.

Dadle el nombre que queráis a vuestro entorno. Yo al mío, como podéis ver en los screenshots, le he llamado MuleGon AnyPoint Platform.

Añadir variables a nuestro entorno

Los valores a parametrizar en nuestras llamadas los definimos como variables en el entorno que acabamos de crear. Podéis añadir todas las que queráis. Para empezar, y poder hacer login en AnyPoint, vamos a definir cuatro variables:

• ap_username
• ap_password
• access_token
• api-auth-header

Para las dos primeras introduciremos nuestro usuario y pass de AnyPoint.

Crear la request de Login en AnyPoint

Cada vez que vayamos a lanzar una request desde nuestra Collection de Postman es necesario que primeros nos loguemos en AnyPoint. Además, en este proceso de login obtendremos un token de acceso que tendremos que utilizar en las llamadas sucesivas a cualquier Platform API. Por eso, vamos a construir primero nuestra Request de Login y la salvaremos para tener todo esto automatizado. Para ello:

• La URL será https://anypoint.mulesoft.com/accounts/login (en US control Plane)
• La operación será de tipo POST
• Dentro del Body, añadiremos como parámetros de tipo x-www-form-urlencoded username y password. Es aquí donde en la columna de value, en lugar de introducir los valores hardcoded, hacemos referencia a las variables que hemos definido en nuestro entorno. En Postman, la sintaxis para ello es {{variable_entorno}}

Con esto sería suficiente para hacer login en AnyPoint. Sin embargo, un problema con el que os encontraréis habitualmente al continuar haciento llamadas a Platform APIs es el de “invalid csrf token”.

Las peticiones a las Platform APIs están protegidas ante ataques de tipo Cross-Site Request Forgery. Para evitarlo tenemos que hacer un par de cosas en nuestro Workspace de Postman.

• Añadir *.mulesoft.com a la Whitelist de dominios. Para ello seleccionaremos la opción de Postman Cookies en la parte derecha y haremos click en Add para añadir un dominio. Añadimos la entrada *.mulesfot.com

 

• Además, vamos a añadir un Test Script a esta request. Los Test Scripts en Postman son acciones que se ejecutan justo después de recibir la respuesta de la request que hacemos y que los escribimos en Javascript. Con este script vamos a hacer tres cosas:
• Limpiar las Cookies.
• Guardar el access token que obtendremos como respuesta de AnyPoint al logarnos. Este access token lo guardaremos de forma automática al ejecutar esta llamada en la variable de nuestro Entorno que hemos definido como access_token.
• Por último, construimos el header de autenticación para poder parametrizar el valor de este header en llamadas sucesivas.

const jar = pm.cookies.jar();

jar.clear(pm.request.url, function (error) {

console.log("Clear Cookies");

});

var response = pm.response.json();

var access_token = response["access_token"];

pm.environment.set("access_token", access_token);

pm.environment.set("api-auth-header", "Bearer " + access_token);

console.log("Access Token " + access_token);

Con todo esto ya tenemos preparada nuestra request de login. Hacemos click en Send y, si todo lo hemos configurado correctamente, recibiremos como respuesta un 200 con el token de acceso. Además, si echamos un ojo a las variables de nuestro Entorno veremos que nuestras variables access_token y api-auth-header ahora tienen un valor.

Finalmente, solo nos queda crear nuestra Collection y guardar esta request que hemos construido ahi. Yo la he llamado Login. Aqui os dejo el enlace de Postman sobre cómo crear Collections y guardar Requests.

2. Peticiones sucesivas

En cada petición que hagamos a una Platform API va a ser necesario que añadamos un token de acceso. Este token lo pasaremos como una cabecera Authorization. Gracias a los pasos anteriores, hemos automatizado el proceso de login, la obtención de este access token y hemos preparado el valor de esta cabecera como variable de nuestro Entorno.

Por tanto, cada vez que iniciemos una sesión de llamadas a Platform APIs, solo debemos lanzar nuestra request guardada de Login y después el resto de peticiones a realizar añadiendo la cabecera Authorization. Para automatizar también esto, lo que haremos será salvar cada request que nos sea util (o que vayamos a realizar con frecuencia) dentro de nuestra Collection asegurándonos que en cada request tenemos la cabecera con dicho valor.

Para ello, por ejemplo, hagamos un GET a la Platform API que nos da información sobre el usuario logado. La URL del endpoint a utilizar será https://anypoint.mulesoft.com/cloudhub/api/me y en el tab de Headers introduciremos el valor de nuestra variable {{api-auth-header}}. 

Por último, si nuestra request ha funcionado, la salvamos dentro de nuestra Collection. Así, la próxima vez que necesitemos hacer esta llamada, sólo tenemos que hacer dos clicks: uno en la request de Login y otro en esta última request. No nos tendremos que preocupar más de introducir usuario, password o de copiar/pegar el token y construir el header de Authorization.

Resumen

Como habéis visto, el uso de Postman para interactuar con las Platform APIs nos facilita mucho el trabajo. Sólo nos hace falta crear nuestro Environment y nuestra Collection de requests. Mi consejo es, además de lo que acabamos de hacer en este post, que mantengáis y vayáis actualizando vuestro Environment y vayáis añadiendo Requests de cada operación que descubráis util. En mi caso, por ejemplo, yo tengo añadidas algunas variables más en mi Environment:

• org_id - El ID de vuestra org lo vamos a utilizar en muchas Platform APIs
• environment_id - El ID del entorno con el que vayamos a trabajar.
• host - El hostname de la URL en Platform APIs es distinto en función del Control Plane al que nos estemos conectando. En mi caso, que manejo varias Orgs, para no andar cambiandolo lo he parametrizado y cambio su valor en función del Control Plane:
• anypoint.mulesoft.com para US Control Plane
• eu1.anypoint.mulesoft.com para EU Control Plane

Para finalizar, si no queréis empezar de cero a construiros vuestro Entorno y Requests os aconsejo empezar por este tutorial de mi compañero Angel Alberici donde os enseña a hacer unas cuantas llamadas a Platform APIs y, además, os proporciona, en este enlace a su repositorio GitHub, un Environment y Collection preparados para que podáis importarlas en vuestro Workspace.

A enredar con las Platform APIs se ha dicho...