Puede que muchos estéis familiarizados con el consumo e implementación de APIs pero puede que no seáis del todo conscientes de la importancia de un buen Gobierno de APIs (API Governance) dentro del proceso global del API Management.
Este tutorial no pretende ser un guía teórica de las pasos que se tienen que dar para implementar un correcto API Governance. Lo que busca es que con sencillos ejemplos de casos ficticios (pero que podrían ser perfectamente reales) se conozca la importancia de la implantación un buen Gobierno de APIs dentro de una organización. Los ejemplos usados en este artículo si bien no son reales, son muy similares a casos que durante mi experiencia laboral me he ido encontrando a lo largo de los años. Veremos sus riesgos y sobre todo como un buen Gobierno de APIs es capaz de minimizar o incluso eliminar éstos.
Índice de contenidos
Introducción
¿Qué es el Gobierno de APIs? No es fácil encontrar una definición exacta de qué es el Gobierno de APIs. Podríamos decir que es una parte muy importante (posiblemente la más importante) dentro del proceso global de Gestión de APIs. El Gobierno de APIs nos va a ayudar sobre temas como documentación, política de versionado, seguridad, diseño, monitorización, testing, etc. Es decir, va a estar presente a lo largo de todo el ciclo de vida de nuestras APIs.
Los objetivos principales del Gobierno de APIs son la estabilidad y la coherencia. Con la estandarización de muchos procedimientos dentro del ciclo de vida de un API hará que nuestra organización cuente con una cierta coherencia que eliminará muchos problemas a corto/medio plazo. Si mantenemos dicha coherencia en nuestra APIs y usamos determinadas herramientas y metodologías además dotaremos a nuestro Negocio de una estabilidad vital.
Escenario
Vamos a dibujar nuestro escenario ficticio, pero seguro que muchos lo podéis extrapolar a vuestras empresa o clientes en los que habéis trabajado.
Somos una empresa de tamaño medio pero que poco a poco va creciendo y donde se usan APIs a nivel interno y externo como parte fundamental del Negocio. Estas API han sido desarrolladas durante años por empleados que en algunos casos ya no están en la empresa y con una gran variedad de perfiles, desde becarios hasta arquitectos. En el punto en el que está la empresa se está empezando a lograr una considerable monetización de sus APIs, además del uso interno que existen dentro de la propia organización.
Con este escenario empiezan a aparecer algunos problemas dentro de nuestra organización que en muchas ocasiones llegan a afectar directamente a la calidad del servicio y en definitiva al Negocio de nuestra empresa:
- ¿Qué APIS existen actualmente desarrolladas?
- ¿Hay documentación de éstas APIs? ¿dónde está?
- ¿Qué naming y verbos uso para la nueva APIs que estoy diseñando?
- ¿Cuál es la política de versionado de mis APIs?
- ¿Cuántas versiones activas mantengo?
- ¿Qué hago con las versiones deprecadas?
- ¿Puedo eliminar una versión?
- ¿Quién consume mi API?
- ¿Hay algún tipo de monitorización? ¿dónde está?
- ¿A quién notifico las modificaciones de mi API?
Equipo de Gobierno
A continuación se introduce el término de Equipo de Gobierno, que a muchos les puede resultar novedoso pero que una vez visto en detalle seguro que os puede venir a la cabeza otros equipos como Arquitectura, etc.
Un Equipo de Gobierno es un conjunto de personas de diferentes perfiles encargadas de velar por la estabilidad y coherencia del API Management de una organización. En muchos casos esta parte no está muy bien definida y no queda claro quién/es son los encargados de formar este equipo porque en algunas ocasiones ya forman parte de otros equipos.
Es recomendable que la gente que forme parte de dicho equipo tenga diferentes perfiles: arquitectura, experto funcional (Business Analyst), seguridad, technical leader, desarrollo, etc. Es decir, gente con ciertas habilidades de gestión, comunicación, liderazgo; gente con habilidades más técnicas (API Specialist, API Evangelist…).
El objetivo de un Equipo de Gobierno será:
- Gestionar todo el ciclo de vida de un API.
- Establecer unas buenas prácticas dentro del diseño e implementación de APIs (evangelización).
- Establecer una metodología de trabajo óptima a la hora de la Gestión de APIs.
Se pueden ver ya los conceptos más importantes, ¿verdad? Gestión, buenas prácticas, metodología. Todos orientados a los objetivos fundamentales: coherencia y estabilidad.
Todo el Mundo tiene que tener claro quiénes son este Equipo de Gobierno, ya que van a estar presente en todo el ciclo de vida de un API. Es importante dar visibilidad mediante la creación de buzón de email específico, crear espacios de trabajo, canales/chats dedicados, etc.
Gobierno del ciclo de vida de un API
Ahora vamos a ver desde el inicio hasta el final del ciclo de vida de un API como interviene (o debería) un Equipo de Gobierno y los beneficios que tiene.
Inicio
Tras los aspectos más comerciales se inicia con una(s) reunión(es) de Kick off donde están presentes varios perfiles y donde tiene que estar obligatoriamente el Equipo de Gobierno. Es posible que no tengan que asistir todos los miembros (perfiles) a esta reunión. Puede que con el Responsable, Arquitecto y experto funcional sea suficiente por ahora en estas primeras reuniones. Se analizarán de las necesidades de negocio así como las posibles interacciones entre APIs internas/externas ya existentes o nuevas a desarrollar.
Puede que lo que se necesite ya esté implementado en la actualidad pero el desconocimiento de que APIs están disponible puede hacer trabajar por duplicado. Por ello se tienen que tener catalogados todas las APIs de una organización (API Discovery). En este catálogo tienen que aparece todas las APIs junto con su documentación tanto funcional como técnica. Ya veremos más adelante cómo se puede implementar dicho catálogo de forma más eficiente pero la gran mayoría de los API Managers tienen un API Portal o Portal del desarrollador.
Posibles problemas:
- El equipo de seguridad no está involucrado en estas reuniones y se detectan vulnerabilidades después de la integración entre APIs.
- No existe un catálogo actualizado de APIs internas y se duplican APIs (servicios).
- Rendimiento esperado del API (servicio) no está claro o indeterminado (necesidad de escalado).
Diseño
Es fundamental aplicar una serie de buenas prácticas en cuanto al diseño de nuestras APIs con el fin de estandarizarlas y establecer una coherencia entre ellas. Desde como interactúan diferentes APIs entre sí, el naming, correcto uso de los verbos y códigos de respuesta, gestión de errores, etc. Una vez analizado todo esto en profundidad con los perfiles más técnicos se puede llegar a un acuerdo de interfaz (Contract First). Esto ayuda a garantizar que las API sean consistentes y reutilizables.
Si esto se cumple no vamos a encontrarnos con APIs cuyos verbos no son los correctos, los códigos de respuesta no son los adecuados o el naming no es el mismo para todos ¿A qué os ha pasado esto alguna vez? ¿El Equipo de Gobierno ha estado presente en el diseño del API? Si hubiese estado todas las nuevas APIs tendrían una definición y diseño homogéneo. El cómo se implemente ya es otra cuestión pero por lo menos se tiene un catálogo actualizado con un diseño común a todas las APIs de la organización por lo que la integración entre APIs siempre va a ser mucho más sencilla reduciendo tiempos y problemas.
En este punto se recomienda invitar a miembros de otros equipos a participar activamente con el fin de evangelizar, es decir, poner encima de la mesa todas estas buenas prácticas para que se vayan distribuyendo por todos los equipos. No se tiene que quedar en «el Equipo de Gobierno me dice cómo tengo que llamar a mi nueva API, los verbos, códigos de respuesta y me define el acuerdo de interfaz«. El Equipo de Gobierno tiene como objetivo hacer entender al resto de equipos el porqué se toman las decisiones que se toman en cuanto al diseño se refiere.
Posibles problemas:
- Acuerdo de interfaz poco sólido o indeterminado (problemas en la integración final). Cuanto más cariño se dé a esta parte entre todas las partes menos problemas vamos a encontrarnos en el proceso de integración.
- Herencia de malas prácticas con verbos, naming, códigos de respuesta, etc.
Desarrollo
Documentación
Una vez que se tiene claro la interfaz se pasa a la parte de la documentación del APIs donde el Equipo de Gobierno tiene que determinar una serie de pautas y herramientas para llevar a cabo este paso. Dentro de todas las posibilidades que se tienen en el mercado para documentar APIs tienen que tomar la decisión de elegir la qué mejor se adapte a sus necesidades: Swagger, RAML, Stripe, API Blueprint, etc.
Lo habitual es que está decisión no dependa de un API en concreto sino que sea una decisión previamente tomada a nivel corporativo. Posiblemente se necesitará crear usuarios, permisos, roles para empezar a hacer la documentación de nuestro API.
Implementación
Muchos pueden pensar que la fase de implementación no forma parte del Gobierno de APIs pero siempre es bueno, tal y como se ha hecho con el diseño, que en la medida de lo posible se homogenice la implementación a nivel de frameworks, librerías, clientes, timeouts, etc. En esta fase evidentemente toman protagonismo los perfiles más técnicos del Equipo de Gobierno que se deberían encargar de formar, si es necesario, y establecer una serie de buenas prácticas para la implementación del API.
Posibles problemas:
- Documentación incompleta o no actualizada. Esto va a provocar una implementación incorrecta por lo tanto problemas en la integración.
- ¿Quién es el propietario de la documentación? ¿El Equipo de Gobierno? ¿El equipo de desarrollo? El Equipo de Gobierno toma parte en esta fase pero lo normal es que el propietario de la documentación del API sea el equipo de desarrollo. Esta parte tiene que quedar muy clara ya que el propietario será el encargado del mantenimiento de dicha documentación (actualizaciones, versionado, etc.).
Uso o consumo del API
Esta fase de uso o consumo del API es vital, posiblemente sea la fase donde más riesgos podemos encontrar si no se hace correctamente el Gobierno de APIs. Un API está hecha para ser consumida, bien sea interna o externamente, para ello aparece el rol del consumidor que puede ser otra API, un frontal (web, apps, etc) o cualquier otro componente.
Es vital tener el conocimiento en todo momento que consumidores tienen nuestras API.
Los consumidores se podrán subscribir a nuestras APIs desde el API Portal o Portal del desarrollador. Esta subscripción podrá ser libre o bajo demanda, según la tipología tanto del API como el consumidor. Es decir, puede que para nuestra organización no dejemos que cualquier consumidor se subscriba libremente a nuestras APIs sino que alguien del Equipo de Gobierno o desarrollo confirme dicha subscripción.
Hay que tener presente en todo momento la capacidad de nuestras APIs (servicios), es decir, cuántas peticiones por segundo son capaces de procesar (máximas y esperadas). Y aquí es donde aparece otro concepto importante como las cuotas. Es decir, qué cantidad de peticiones por segundo voy a otorgar como máximo a un consumidor para que haga uso de una determinada API. Para ello, como hemos dicho anteriormente es vital analizar previamente el rendimiento de nuestra API y en función de eso, de la tipología del API, del tipo de consumidor (interno o externo) determinar que nivel de servicio o cuota le vamos a dar para el consumo de nuestra API.
Cada consumidor tiene que tener varios responsables (funcional y técnico) y una forma de contacto (preferiblemente un buzón de correo electrónico). Todo cambio de un API tiene que ser comunicado a todos sus consumidores (nuevas versiones, cambios retrocompatibles, versiones deprecadas, versiones eliminadas, cambios en la documentación, etc.).
Posibles problemas:
- Se desconoce realmente quién consume nuestras APIs y qué versión. Si se desconoce este hecho la verdad es que tenemos un problema bastante importante ya que no vamos a poder deprecar o eliminar versiones sin riesgo, y es justo una palabra que se tiene que evitar usar cuando se trata de Gobierno de APIs. Por ejemplo, imaginaos que nuestro negocio trata de la logística de órganos para transplantes entre diferentes hospitales. Si no sabemos al 100% qué consumidores tiene mi API…¿se podría eliminar una versión/API dejando a un hospital sin este servicio?.
- Mala gestión de cuotas. No se analiza en detalle ni la tipología del API ni del consumidor y se establecer cuotas por defecto. Esto puede provocar la saturación o incluso caída del servicio. Por ejemplo: no analizamos a fondo el rendimiento de nuestra API ni tampoco prestamos atención a los consumidores estableciendo cuotas máximas para todos. Damos la misma cuota a un consumidor de una empresa pequeña que una empresa internacional que está pagando (monetización) por el servicio. Puede que la empresa pequeña pagando 100 veces menos que la empresa grande haga un uso elevado de nuestra API y la empresa grande vea ralentizadas sus peticiones o incluso se provoque una caída del servicio con la pérdida de dinero y prestigio que conlleva.
- Se usa un único email de responsable técnico (no un buzón) para un consumidor y tras el paso de los meses esa persona sale de la empresa por lo que producen errores en las notificaciones de las APIs consumidas.
Monitorización
Mediante la monitorización vamos a saber el consumo real de nuestras APIs. No sólo si los consumidores están consumiendo realmente sino la forma en la que lo hacen (picos, franjas horarias, etc). Monitorizando nuestras APIs vamos a poder tener un elemento importante para poder refinar las cuotas a aplicar a los consumidores. También nos va a servir para determinar o modificar políticas de escalado de nuestros servicios.
Gracias a la monitorización vamos a poder generar estadísticas e informes a diferentes departamentos de nuestra organización como IT, Negocio, Marketing, etc.
Además nos va a servir para implementar algún sistema de alertas que notifique algún comportamiento anormal o inusual del consumo de nuestras APIs.
Versionado y eliminación
Otra de las partes fundamentales a tener en cuenta en el ciclo de vida de un API es la que tiene que ver con el versionado y la eliminación de determinadas versiones/APIs.
Es necesario notificar a todos los consumidores de cualquier cambio relacionado con el API y/o documentación. Es necesario enviar un fichero changelog con los cambios así como la documentación si fuese necesario.
El Equipo de Gobierno en la fase Inicial y/o Diseño tiene que determinar cuántas versiones se mantienen activas. Para ello es importante saber el TTL de una versión. Es decir, el tiempo que una versión permanece activa en producción. Puede que por la tipología del API se publiquen nuevas versiones cada 2 meses, cada 6 meses o cada 2 años por ejemplo. Esto afecta directamente al número de versiones que se esperan tener activas pudiendo ser un problema tanto para quien hace la implementación como para quién consume el API.
Este análisis inicial puede cambiar en el futuro pero nos puede servir para informar a los consumidores de nuestras APIs (generalmente externos) sobre este proceso de versionado y eliminación con el fin de tener en cuenta posibles procesos de migración. Esta parte es más comprometida ya que en muchas ocasiones podemos encontrarnos con integraciones de terceros «a proyecto cerrado«, es decir, se integran con una determinada versión y luego no tienen la capacidad (de equipo, de presupuesto, etc.) de migrarse a versiones superiores.
Posibles problemas:
- Una mala definición del API y/o servicio puede provocar la necesidad de crear demasiadas versiones en muy poco tiempo.
- Tener muchas versiones activas conlleva una sobregestión y problemas de mantenibilidad en código.
- Puede ocurrir que determinados consumidores no puedan integrarse con las nuevas versiones (temas contractuales, disponibilidad, etc.). ¿Y ahora qué hacemos? Si una empresa (consumidor) se ha integrado con la v1 de nuestra API y cuando deprecamos esta versión luego no podemos eliminarla en el futuro porque la empresa no tiene necesidad ni capacidad para migrarse de versión. El Equipo de Gobierno tiene que tener esto siempre en mente y establecer de alguna forma una política de versionado/eliminación consensuado con los consumidores.
- Se versiona el código (API y lógica) pero no se versiona la documentación.
Conclusiones
Una vez leído el artículo queda claro la importancia de un buen Gobierno de APIs dentro de una organización. El software es un elemento vivo, tiene un ciclo de vida muy claro. No tenemos que quedarnos sólo en la pura implementación de nuestros servicios y APIs. Tenemos que tener en mente en todo momento la necesidad de gestionar todo su ciclo de vida y para ello tenemos los API Managers que podríamos decir que son «la implementación del Gobierno de APIs«.
Un API Manager es un conjunto de herramientas cuyo objetivo es ayudar a realizar gran parte de las tareas del Gobierno de APIs. Nos va a ayudar a cubrir todas aquellas necesidades que se han visto anteriormente para poder realizar un correcto Gobierno de APIs.