5 cualidades clave de una API
¿Es la API de mi proveedor el verdadero impostor? ¿O fuimos nosotros los que no hicimos las preguntas correctas durante la investigación?
La mayoría de las compañías en algún momento de su vida se encuentran con la necesidad de tercerizar un servicio y las empresas con productos digitales no son la excepción.
Los sistemas que desarrollamos muchas veces necesitan de otros subsistemas más complejos para funcionar, tan complejos que es conveniente buscar un tercero que ya lo haya resuelto.
Por ejemplo, si nuestro producto necesita recibir pagos en distintas monedas, algún subsistema se encargará de proveer el tipo de cambio actualizado y algún otro tendrá que procesar el pago.
Muchos proveedores nos van a dar una API junto con su documentación para que logremos integrar nuestros sistemas. Esta conexión o integración conlleva un riesgo, si la API del proveedor funciona mal, nuestro sistema va a funcionar mal, como bien dice el dicho, "una cadena es tan fuerte como su eslabón más débil".
Entonces, si queremos que nuestro sistema funcione bien, es fundamental que encontremos al proveedor con la mejor proporción precio/calidad.
Como parte del equipo técnico, nuestra misión es analizar si las APIs cubren nuestros casos de uso y estimar con la mayor precisión posible, el componente calidad de esa ecuación.
Hay muchos aspectos que contribuyen a la calidad, a continuación te cuento sobre cinco cualidades clave comúnmente olvidadas durante el análisis de una API.
Sincronización de Datos
Rendimiento y Disponibilidad
Retrocompatibilidad
Comprobabilidad
Resiliencia
Sincronización de Datos
La sincronización de datos es un proceso que ocurre cuando necesitamos obtener información de la API para actualizar datos de nuestra plataforma.
Por ejemplo, el estado de mis movimientos depende del estado de tus transacciones, o mis suscripciones representan tus pagos recurrentes, o mis notificaciones son producto de tus eventos.
La actualización puede darse de forma síncrona, es decir, tengo feedback inmediato de los cambios que realizan mis requests en los datos del proveedor, o de forma asíncrona, es decir, hay un procesamiento que ocurre sin que mi sistema lo esté esperando. En ambos casos, tenemos que mapear los datos de la API con los nuestros, lo que cambia es el momento en que nos enteramos.
Además, la actualización asíncrona viene generalmente en dos sabores distintos: o nos envían un webhook para avisarnos que se actualizó algún dato, o tenemos que hacer un cron que haga un fetch cada un tiempo determinado.
Algunas preguntas clave que podemos hacer relacionadas a la sincronización de datos de una API son:
¿Cómo puedo mantener actualizada mi entidad X con los cambios de tu entidad Y?
¿Qué pasa si mi servidor está caído cuando me envías el webhook?
¿Cada cuánto debería hacer el fetch de tu entidad Y?
Rendimiento y Disponibilidad
El rendimiento y la disponibilidad de una API son tan importantes que incluso deberían ser mencionados en el contrato que firmemos con nuestro proveedor.
El rendimiento estará determinado por la velocidad y concurrencia que soporte la API. Por otro lado, la disponibilidad estará sujeta al porcentaje de errores obtenidos. No existe sistema alguno que no falle nunca. La API que integremos va a fallar esporádicamente y es un riesgo que tenemos que asumir o mitigar. La estrategia que implementemos dependerá de la probabilidad de fallo y del impacto del mismo.
Por este motivo, es una buena idea auditar las interacciones con las APIs de nuestros proveedores. De esa forma, tenemos métricas que pueden llegar a ser útiles para reclamar en caso que sea necesario y también nos sirve para depurar errores.
Algunas preguntas clave que podemos hacer relacionadas al rendimiento y disponibilidad de una API son:
¿Cuántos request por minuto soporta tu API en promedio?
¿Cuál es la latencia promedio esperable?
¿Puede haber latencias más altas de lo normal? ¿En qué momentos del día?
¿Podrían compartirnos métricas de algún stress test que hayan corrido recientemente?
¿Qué porcentaje de uptime tiene tu sistema?
¿Cuál es la tasa de fallo por día de tu API?
Retrocompatibilidad
Así como nuestro sistema está en constante evolución agregando funcionalidades y mejorando todos los días, el sistema de nuestro proveedor también.
La retrocompatibilidad define qué tanto nos van a afectar los cambios que hagan sobre la API. En otras palabras, nos va a definir cada cuánto vamos a tener que hacer mantenimiento a la integración que desarrollamos.
¿Qué cambios se consideran no retrocompatibles? Algunos ejemplos son:
Agregar campos obligatorios
Modificar la URL de los endpoints
Cambiar el formato de las respuestas
Cambiar los códigos de respuesta
Cambiar el nombre o tipo de dato de algún campo obligatorio
Si bien el cambio es algo inevitable, hay estrategias que nuestro proveedor puede tomar para disminuir el impacto, una de ellas es versionar la API. Una API bien versionada nos tiene que asegurar que todos los cambios que se hagan sobre una versión específica, no nos obliguen a modificar nuestro código.
Hay que tener en cuenta que las versiones de una API tienen un tiempo de vida. Va a llegar el día que nuestro proveedor decida discontinuar una versión y en ese caso es importante que nos avisen con tiempo para poder planificarlo en nuestro roadmap.
Algunas preguntas clave que podemos hacer relacionadas a la retrocompatibilidad de una API son:
¿Cómo manejan el versionado de su API? ¿Cada cuánto suben una nueva versión?
¿Con cuánto tiempo nos van a avisar sobre cambios que rompan la compatibilidad?
Comprobabilidad
La comprobabilidad es la capacidad que tiene un sistema de ser puesto a prueba en sus diferentes flujos.
Necesitamos poder hacer pruebas sobre los distintos errores y respuestas que contemplamos en la integración, y puede que el ambiente de pruebas de nuestro proveedor no esté preparado para reproducir todos los casos detallados en la documentación de su API.
Dado ese escenario, corremos el riesgo de que algún flujo tenga un error y no lo detectemos hasta que ocurra en producción. Una forma de mitigar este riesgo es desarrollar una API mock para reproducir los escenarios que le hagan falta al sandbox del proveedor.
Algunas preguntas clave que podemos hacer relacionadas a la comprobabilidad de una API son:
¿Tienen un ambiente de pruebas al que podamos integrarnos en ambientes bajos?
¿Cómo pruebo los distintos códigos de error que devuelve su API?
Resiliencia
La resiliencia es la capacidad de un sistema para continuar funcionando incluso cuando ocurre un error. Como dijimos previamente, la API de nuestro proveedor va a fallar y es inevitable. Sin embargo, hay formas de convertir estos fallos en éxitos, una de ellas es implementar una lógica de reintentos ante errores.
Implementar reintentos es responsabilidad de nuestro sistema, pero el ser reintentable es responsabilidad de nuestro proveedor.
¿Qué debería tener una API reintentable? Algunos ejemplos son:
Asegurar que el reintento no duplique operaciones
Documentar que errores son finales
Mantener una misma respuesta para un mismo request
Muchas APIs utilizan un id de transacción o de idempotencia en sus requests para mejorar la resiliencia. Ese id es único para cada request, de esa forma pueden guardar en una caché el estado del mismo y asegurar que no se repitan operaciones que deben ocurrir una sola vez.
Por ejemplo, si utilizamos una API para transferir dinero, queremos estar 100% seguros que esa transferencia va a ocurrir una única vez ante un reintento.
Algunas preguntas clave que podemos hacer relacionadas a la resiliencia de una API son:
¿Ante qué errores es seguro reintentar un request?
¿Tienen algún límite de cantidad reintentos?
¿Cuánto tiempo debería esperar para reintentar un request?
¿Qué ocurre si envío el mismo request dos veces seguidas?
Conclusiones
Si bien hay varias otras cualidades fundamentales a la hora de investigar una API, los discutidos en este post son los que más he visto ser pasados por alto y que tienen un fuerte impacto en la calidad de una API.
Espero que este post les sirva para hacer mejores preguntas a sus proveedores y así poder evaluar precisamente si la integración les va a traer más problemas que soluciones.
