Mocking Service Behavioral Headers
MuleSoft Mocking Service
El API mocking service nos permite simular el comportamiento de una especificación de una API. Para esto, básicamente lo único que necesitamos tener listo es la especificación de nuestra API (RAML/OAS). Esta es una de las grandes ventajas que ofrece Anypoint Platform a través de Design Center y Exchange, la plataforma generará un API mocking service automáticamente sin hacer más nada. Ni una línea de código adicional, ¡nada!
De esta forma, al estar diseñando nuestra API, la plataforma automáticamente actualizará y publicará el API mocking service. Incluso, el API Portal está disponible en Design Center del lado derecho de la pantalla. En caso de querer interactuar con la versión actual de la especificación, podemos hacerlo a través de este API Portal:
Es importante mencionar que este API mocking service estará disponible por default únicamente en Anypoint Platform, es decir, protegido. Sin embargo, existe la opción para poder compartir públicamente el endpoint generado. Esto deberá configurarse para que el servicio pueda estar disponible en una URL pública.
Es tan simple como presionar el botón Make Public para que la plataforma despliegue el API mocking service en una URL pública. Desde esta misma configuración también podremos colocar una fecha de expiración de esa URL.
¡Listo! Eso es todo lo que necesitamos para tener un API mocking service disponible en una URL pública. Ahora podemos interactuar con la especificación a través del API Portal en Design Center, o incluso desde cualquier otro cliente como Postman.
Los anteriores son algunos conceptos básicos que quizá ya sabían. Sin embargo, hay algunas características interesantes del API mocking service que he visto se usan poco en los proyectos de la vida real pero que pueden dar una experiencia más real a los consumidores de las APIs, incluso en una fase temprana del diseño.
Una de esas características es el tema principal de esta historia: los encabezados de comportamiento, o bien: Mocking Service Behavioral Headers.
¿Qué son los Mocking Service behavioral headers?
No son otra cosa sino HTTP headers que podemos utilizar en las peticiones para cambiar el comportamiento default del API mocking service. Lo mejor de todo es que son out-of-the-box, significa que no debemos hacer nada para agregarlos, sino ¡sólo hacer uso de ellos!
MS-Delay
Típicamente una llamada al mocking service deberá responder dentro del orden de los milisegundos. Normalmente el tiempo de respuesta es muy estándar.
Sin embargo, en los proyectos de la vida real eso no es siempre así. Una API puede tener una o varias dependencias y su tiempo de respuesta dependerá de varias condiciones como: latencia, tiempos de respuesta del backend, performance tuning, entre otras.
Podemos utilizar el encabezado MS-Delay para simular algunas de estas condiciones, de esta forma los consumidores podrán simular y configurar parámetros como timeouts o manejo de errores, cuando de forma atípica nuestra API tarda más tiempo en responder en escenarios de carga o latencia en la red. Este encabezado puede configurarse con un valor entero o un rango de enteros, usando el siguiente formato: min-max. El valor máximo permitido es 10000 y está expresado en milisegundos.
De forma aleatoria, el mocking service agrega tiempo de respuesta simulado dependiendo del rango configurado, al tiempo de respuesta real del mocking service. En el ejemplo utilicé un valor de 50–2000, esto significa que el mocking service agregará un tiempo de respuesta simulado de entre 50 y 2000 milisegundos, de forma aleatoria, al tiempo de respuesta real. En este caso el tiempo de respuesta fue de 1869 milisegundos.
MS-Error-Level y MS-Error-Rate
Lo ideal es colocar en nuestra especificación de API no sólo los códigos de éxito, sino también los códigos de error posibles. Estos códigos normalmente deberán responder a buenas prácticas y estándares de la industria. Por ejemplo, los códigos 4xx indican una falla en el consumidor (parámetros de entrada) y los 5xx indican una falla del lado del servidor.
En el caso de la especificación de este ejemplo, contiene el código HTTP 200 para el caso exitoso y HTTP 404 para indicar que un producto no ha sido encontrado.
Una combinación del encabezado MS-Error-Level y el encabezado MS-Error-Rate dan como resultado un comportamiento aleatorio. Es decir, en ocasiones la API responde de forma exitosa (HTTP 200) y en otras ocasiones responde con error (HTTP 404).
Esto es bastante útil para que los consumidores puedan simular escenarios de error e implementar el manejo de errores correspondiente.
El encabezado MS-Error-Level puede tener los siguientes valores:
- REQUEST_ONLY: el mocking service usará sólo los códigos 4xx.
- SERVER_ONLY: el mocking service usará sólo los códigos 5xx.
- ALL: el mocking service usará ambos códigos de error (4xx y 5xx). Este es el valor default.
El encabezado MS-Error-Rate es un valor decimal entre 0 y 1 que indica la probabilidad de obtener un código de error como respuesta. En el caso del ejemplo, el valor es 0.5. Esto significa que la API devolverá un código de error el 50% de las veces.
Otros Behavioral Headers
Existe una lista completa de los encabezados que podemos utilizar en el mocking service para dar a nuestra API un comportamiento más real incluso en tiempo de diseño. Todos ellos están en la documentación oficial de MuleSoft. Aquí les dejo la lista y una breve descripción de ellos:
- MS2-Example: elige específicamente alguno de los ejemplos de respuesta de tu API, si has definido en el mismo endpoint más de un ejemplo. El valor del header deberá corresponder al nombre asignado a cada uno de los ejemplos. Si proporcionas un valor que no esté definido en la especificación, el mocking service devolverá un error.
- MS2-Randomize: si se especifica como true, el mocking service generará de forma automática un payload de respuesta si es que no se ha especificado un ejemplo. La respuesta automática siempre estará adherida a los tipos de datos y restricciones definidos en la especificación.
- MS2-Status-Code: funciona como un filtro. Si hemos definido múltiples códigos de respuesta en nuestra API, este encabezado indicará al mocking service cuáles de todos ellos puede elegir de forma aleatoria. La lista de códigos de respuesta se debe separar por comas: 2xx, 4xx, 5xx.
- MS2-Status-Code-Selection: por default el mocking service elige el código de respuesta menor definido en la especificación. Por ejemplo, si hemos definido múltiples códigos de respuesta: 200, 400, 404, 500, el mocking service utilizará siempre 200. Con este encabezado podremos seleccionar el código de respuesta menor (FIRST), o bien, un código de respuesta aleatorio de todos los disponibles en la especificación (RANDOM).
Conclusiones
En tiempo de diseño, aún cuando no tenemos lista la implementación de las APIs, el API mocking service puede proveer de comportamiento real simulado a través de los Mocking Service Behavioral Headers.
De esta forma podemos proporcionar comportamiento cercano al real a los consumidores de las APIs. Así, éstos podrían simular escenarios tanto de éxito como de error y realizar el manejo de errores correspondiente sin necesidad de tener completa la etapa de implementación.
Esto ayuda a agilizar el desarrollo y entrega no sólo de las APIs, sino también de las experiencias y aplicaciones que se construyen haciendo uso de ellas, al proporcionar comportamiento real en etapas muy tempranas del ciclo de vida.
Hasta aquí la historia de hoy. Comentarios, retroalimentación, sugerencias, preguntas y cualquier interacción son bienvenidas.
¡No olviden seguirnos a través de todos los canales de MuleSoft Community!
