¿Por qué hace falta gobernar las APIs?

Las APIs son una imagen externa e interna de las empresas que exponen en forma de producto ciertos activos de datos o funciones definidos expresamente para su consumo a través de una interfaz documentada y sencilla de utilizar.

Enlazando esta idea con el concepto de API Economy, mediante el cual las empresas impulsan su crecimiento con el consumo y la monetización de las APIs, estos productos digitales se convierten en un activo estratégico de negocio.

Hoy en el blog veremos por qué es necesario gobernar las APIs y cuál es la manera más óptima para hacerlo.

Resulta básico establecer una estrategia que favorezca la adopción de estos componentes de negocio, para lo cual es necesario:

• Involucrar a negocio. Las APIs no son meramente tecnología, sino que constituyen un producto en sí mismo. Es negocio quien tiene el mayor conocimiento funcional y sin su respaldo las APIs son una implementación tecnológica más sin impacto, desaprovechando su potencial.
• Establecer objetivos marcando plazos y usando métricas para controlar su cumplimiento.
• Definir roles y responsabilidades estableciendo quién hace qué y en qué momento en el flujo de trabajo.
• Dar visibilidad a la iniciativa evangelizando la disciplina y difundiendo los estándares y buena prácticas establecidos dentro de la organización.

Las funciones del equipo de gobierno en este tipo de iniciativas es el de:

• Coordinar a todos los intervinientes.
• Definir y mejorar la metodología de trabajo de manera constante.
• Establecer un marco de actuación común, para lo cual establece estándares y buenas prácticas dentro de la organización y forma a todos los involucrados en estos estándares
• Por último, gestionar el ciclo de vida de las APIs y su evolución.

En resumen evita la descoordinación entre alguna de las partes para evitar poner en peligro la iniciativa y obtener de los objetivos definidos.

¿Qué hace un equipo de gobierno de APIs?

Fomentar la transparencia

Se encarga de recopilar el conocimiento en el catálogo de APIs y se convierte en el único punto de entrada para diseñar, organizar y publicar las APIs en dicho catálogo.

Comunica y forma a la organización, independientemente del perfil (negocio o tecnología), en todo el proceso colaborativo del modelo de gobierno.

Estandarización

El core del trabajo desarrollado por el equipo de gobierno es establecer un conjunto de buenas prácticas mediante guías de desarrollo e implementación que tienen como objetivo: homogeneizar el diseño y la documentación de las APIs y facilitar la toma de decisiones en todos los procesos asociados a ellas estableciendo un marco de trabajo común.

Definir roles y responsabilidades

El gobierno es el encargado de identificar a los diferentes participantes e involucrarlos en el flujo de trabajo, estableciendo en qué momento del flujo interviene cada participante y las tareas a realizar en ese punto.

Gestionar métricas

Define los controles y mecanismos de medida mediante KPIs de ámbito técnico para comprobar el uso y buen funcionamiento de las APIs y de ámbito de negocio para cuantificar el éxito y acogida por parte de los desarrolladores que consumen la API.

Definir la metodología de trabajo

El equipo de gobierno se ocupa de establecer el flujo de trabajo y mejorarlo de manera continua gracias a las métricas. También define los canales de comunicación y las ceremonias necesarias (reuniones, comités, dailys, etc) que permiten articular el flujo de trabajo. Además, incluye puntos de control para garantizar el cumplimiento de las buenas prácticas.

Evangelizar a la organización

Impulsa la adopción de soluciones que incorporen APIs y promueve la reutilización de las ya existentes. Garantiza el alineamiento estratégico con negocio y ayuda en la identificación de activos "APIificables" que aporten valor a la organización. También se ocupa de evangelizar sobre el trabajo en comunidad y dinamizarla.

Roles y responsabilidades

Se propone un modelo de trabajo en comunidad, es decir, un grupo de personas de diferente perfil que trabajan de forma conjunta y colaborativa para la entrega de un producto que ofrezca valor a la organización, en este caso una API.

Equipo funcional

Son aquellas personas que tienen un conocimiento profundo del negocio y de la funcionalidad que quieren exponer en la API.

Experto funcional

Persona con conocimiento de negocio que ayuda a la comunidad (gobierno y proyecto) a entender la funcionalidad que se persigue con la API. Trabaja codo con codo con el Product Owner para definir los requerimientos de la API y la categoriza dentro del ecosistema de las APIs de la organización.

Product Owner

Es la persona que actúa de enlace entre tecnología y negocio. Asume la titularidad de la API gestionando su plan de producto y establece los objetivos que se persiguen con su implementación, es decir, define la API en cuanto a prestaciones, segmento de negocio y funcionalidad.

También puede identificar APIs candidatas en los proyectos que esté involucrado.

Equipo de proyectos

Son los encargados de implementar los backend que tienen la lógica de negocio que se expone en la API.

Trabajan con el Product Owner para entender la funcionalidad de negocio que cubre la API y definen de manera conjunta con el API Designer el contrato de interfaz que cumpla dicha funcionalidad.

Equipo de gobierno de APIs

API Designer

Trabaja conjuntamente con el equipo de proyecto en todo el ciclo de vida de la API: diseñan la interfaz de forma conjunta, verifica que la definición cumple con el documento de diseño, garantiza que la documentación de dicha definición sigue los estándares de calidad y nomenclatura establecidos.

También se apoya en el Product Owner para entender la funcionalidad que se quiere exponer en la API, categorizarla y promocionarla donde aplique. Es la persona que configura las políticas de consumo de la API, seguridad, planes de consumo aplicaciones y junto con el API Evangelist .

API Evangelist

Es el experto en las buenas prácticas, normativa de diseño y gobierno de APIs, es decir, es el metodólogo de la disciplina. Ayuda al API designer en la toma de decisiones y certifica el diseño de las APIs garantizando la vitalidad y viabilidad de las soluciones en el tiempo.

Es el encargado de divulgar buenas prácticas a través de guías y estándares incorporando las nuevas normas que aplican a la organización según se vayan necesitando para su homologación.

API Strategy Sponsor

Patrocinador de la disciplina API. Es la persona que se ocupa de liderar la estrategia de implantación y vela por el cumplimiento de la misma.

Trabaja fundamentalmente como gestor de la demanda del equipo de gobierno e interactúa con negocio y los expertos funcionales evangelizando sobre el uso de las APIs.

Ciclo de vida

El ciclo de vida de las APIs, comparado con el diseño de servicios tradicional o SOA, se diferencia por ser un ciclo más ágil, porque los objetivos y requerimientos cambian rápidamente.

Este ciclo es más corto porque las APIs demandan un menor tiempo de elaboración y, además, pueden empezar a ser consumidas sin estar construidos los backend y más flexible porque una misma API puede ser consumida por diferentes tipos de usuarios (internos, partners o externos), a través de diferentes modelos de consumo (gratuito o de pago por uso) y con diferentes configuraciones (seguridad, límites de acceso, etc).

El ciclo de vida se divide en un conjunto de fases que aglutinan todas las tareas que se realizan sobre las APIs, dichas fases pueden clasificarse en:

Fase de diseño

Engloban la identificación de la API, su objetivo funcional y diseño de la interfaz.

Identificación

La identificación de las APIs es el proceso de analizar las necesidades de negocio para obtener un conjunto de APIs que puedan aportar valor a dicho negocio.

Este proceso de identificación tiene dos enfoques:

• Top-down: es iniciado por negocio como una identificación reactiva,
• Botton-up: la identificación botton-up es una identificación proactiva desde tecnología.

El resultado de esta fase es un listado de APIs candidatas a ser construidas y publicadas en el catálogo de servicios de la organización.

El papel de gobierno en esta fase consiste en:

• Guiar a los responsables de negocio para filtrar aquellas APIs que verdaderamente aporten valor y para aterrizar los requerimientos funcionales.
• Ayudar a los proyectos en la estructuración de las APIs candidatas.
• Identificar si esas APIs ya existen parcial o totalmente en la casa.
• Evangelizar a la organización en el modelo API First.

Diseño de la definición

Esta fase se inicia tras filtrar las APIs candidatas y decidir llevar a cabo su implementación. El objetivo es definir la interfaz de los recursos, tanto a nivel de endpoints, campos de entrada y salida, formatos de respuesta y códigos HTTP y a nivel de negocio definir la funcionalidad que se persigue con la API, a quién va dirigida y los objetivos que se pretenden conseguir con su implementación.

El resultado de esta fase es el diseño completo de la interfaz en un documento de análisis.

Para realizar la definición en el documento el API Product Owner junto con el API Designer y el proyecto deben entender en profundidad la funcionalidad que ofrece la API y hacer el diseño siguiendo las buenas prácticas establecidas por el equipo de gobierno.

El equipo de gobierno en esta fase debe supervisar el diseño siguiendo la nomenclatura establecida y asegurando que las APIs que se diseñan aportan valor y una nueva funcionalidad al catálogo.

En esta fase es clave la captura de conocimiento por parte de las personas de gobierno junto con los expertos funcionales y negocio en caso de que aplique, para asegurar que el diseño cumple con la funcionalidad que se busca y cubre todos los requerimientos que se necesitan para lo cual puede ser necesario reunirse de manera habitual.

Fase de desarrollo

En esta fase se crea la definición de la API siguiendo el diseño de la fase anterior, la implementación del servicio backend y la configuración del mismo dentro de la plataforma de gestión de APIs si la hubiera incorporando la configuración de seguridad, límite de accesos, planes de consumo, etc.

Creación

Una vez definida la interfaz de la API en el documento, en esta fase se realiza esa definición en el lenguaje de definición de APIs: Swagger o Raml por parte del equipo de proyecto o el API designer según se defina en el flujo de trabajo.

La tarea que realiza el equipo de gobierno en este punto es validar por parte del API Evangelist la definición implementada en Swagger o Raml para corroborar que cumple lo definido en la fase de diseño, que sigue los estándares y buenas prácticas que establece el equipo de gobierno y que está suficientemente bien documentada como para ser expuesta.

Configuración

En esta fase se toman las decisiones técnicas necesarias para el consumo de la API:

• Configuración de seguridad (Oauth client credentials, resource owner o authorization code).
• Configuración de permisos de acceso y ejecución estableciendo los acuerdos de nivel de servicios.
• Generación de usuarios y/o aplicaciones que pueden consumir la API a través de las correspondientes suscripciones.

Es una buena práctica mockear la API durante esta fase para dejarla lista para los consumidores sin necesidad de tener los servicios back construidos.

Implementación

Implica el desarrollo de la lógica de negocio que hay detrás de la API partiendo de la definición de la interfaz y tras su configuración en la plataforma de gestión de APIs si aplica.

En este sentido pueden darse varias casuísticas: el primero escenario y más sencillo es que la funcionalidad a exponer no se encuentre desarrollada, o que exista de manera parcial por lo que habrá que ampliar el servicio y el escenario más complejo que supone la orquestación de diferentes servicios ya existentes en la casa para ofertar la funcionalidad completa.

En cualquiera de estos escenarios se recomienda el uso de mockups para que los consumidores puedan consumir la API sin dilatar su uso en el tiempo.

Como resultado de esta tarea se obtiene una API preparada para ser consumida por los desarrolladores de aplicaciones.

Es recomendable establecer un canal de comunicación entre gobierno, el equipo de proyecto que hace la implementación y los responsables funcionales siendo el propio equipo de gobierno el que actúa como nexo de unión para solucionar las dudas que surjan y corregir lo que sea necesario.

Gobierno en esta etapa ejerce un rol de soporte en los canales de comunicación definidos, ayudando al desarrollador a seguir la metodología y normas definidas y al Product Owner a comunicarse con el desarrollador en las posibles dudas que surjan a la hora de implementar.

Fase de ejecución

En esta fase se incluyen todas las tareas necesarias para la publicación, monitorización y evolución de las APIs.

Promoción

Esta fase se inicia tras la implementación de lo servicios backend que tienen la lógica de negocio de la API, una vez hecho esto se versiona y publica en el catálogo, es decir, se pone a disposición de la comunidad de desarrolladores para que empiecen a utilizarla.

Por este motivo es fundamental que en la etapa previa se documente la API de la mejor manera posible para que favorezca su uso y la autonomía de los desarrolladores.

Resulta una tarea básica a la hora de publicar una API su catalogación, es decir, categorizar la API en diferentes taxonomías principalmente por dos motivos: para organizar el catálogo de APIs mejorando su usabilidad y para que los desarrolladores sean capaces de encontrar la API que necesitan sin tener un conocimiento profundo del negocio.

Tras la publicación se fomenta el uso de la API por parte de los consumidores poniendo foco en la comunidad de desarrolladores a través de los canales de comunicación establecidos en el flujo de trabajo.

El equipo de gobierno realiza varias tareas:

• Versiona y publica las APIs en el catálogo de la organización y garantiza que la calidad de la documentación es la adecuada.
• Define los canales de comunicación entre gobierno, negocio y tecnología.
• Mantiene viva la comunidad de desarrolladores y recoge el feedback de su uso y funcionalidad.
• Fomenta el uso de las APIs ya publicadas en el catálogo.

Monitorización

Esta fase se inicia tras la definición, catalogación y publicación de la API. Su objetivo tiene dos enfoques:

• Uno funcional más orientado a negocio en el cual se generan informes para cuantificar el cumplimiento de los SLAs y objetivos definidos, cuantificar el uso, la reutilización, la calidad de la documentación y el retorno de inversión con la monetización de las APIs y
• Un enfoque técnico en cuyo ámbito entra la medición del rendimiento de la API, tiempo de ejecución, tiempo de espera a los servicios invocados, etc.

En el aspecto funcional juega un papel clave el feedback por parte de los usuarios para entender cuán buena es el uso y documentación del servicio y si el modelo de monetización es adecuado, para lo cual resultan indicadores evidentes el número de ejecuciones de la API, número de aplicaciones que usan el servicio, etc.

El equipo de gobierno interviene en esta etapa para definir los indicadores que ofrezcan mayor información para la monitorización de la API y son los interlocutores para obtener el feedback de los usuarios.

Valor

Esta fase tiene como objetivo el cobro o retorno de beneficio del uso de las APIs siguiendo el modelo de monetización/valor elegido. La elección del modelo de monetización se realiza en base al tipo de API en la fase de identificación de forma colaborativa entre gobierno, negocio y proyecto para identificar los objetivos que se persiguen con la misma.

Este modelo puede ser desde gratuito hasta cobro por uso directamente al cliente que invoca. El target de los usuarios de las APIs y los objetivos que se consiguen con ellas dependen en gran medida de ese modelo de monetización.

Las APIs gratuitas dan visibilidad a la organización mientras que las de cobro ofrecen un beneficio económico de manera directa.

El equipo de gobierno ayuda a negocio a identificar qué modelo se adapta mejor a la API y cómo se pueden materializar todos los beneficios de las APIs más allá desde un punto de vista económico.

Es en la fase de diseño y ejecución el equipo de gobierno tiene una mayor responsabilidad.

• En el diseño trabaja de manera conjunta con el proyecto para garantizar el cumplimiento de las buenas prácticas establecidas en la casa, la vialidad de la solución y su progresión en el tiempo.
• En la fase de ejecución las principales tareas del equipo son: gestionar la publicación, versionado y socialización de las APIs, interactuar con los consumidores recogiendo su feedback, definir el roadmap de la API y su monitorización mediante KPIs para verificar si se cumplen los objetivos definidos por negocio.

Siguientes pasos

• Mapear los distintos roles dentro de la organización donde se va a establecer el modelo de gobierno de APIs.
• Definir una metodología de trabajo entre los diferentes intervinientes, estableciendo un flujo de trabajo para identificar quién hace qué y cuándo.
• Establecer diferentes canales de comunicación y ceremonias (reuniones, comités, puntos de control, etc) que ayuden a intercambiar la información y a ejecutar el flujo de trabajo en el día a día.
• Desarrollar y promover guías de buenas prácticas en diseño e implementación de las APIs en base al stack tecnológico de las APIs
• Implementar mecanismos de control, métricas y KPIs para valorar el uso de las APIs, la mejora de los servicios y el retorno de valor de los mismos e identificar posibles gaps en el flujo de trabajo para mejorar.

Conclusiones

El equipo de gobierno tiene un papel fundamental en una estrategia de APIficación. A modo resumen se puede decir que sus tareas fundamentales son las siguientes:

• Impulsar la iniciativa involucrando a todos los intervinientes, incluido negocio, coordinando el nivel de implicación de cada uno de los participantes y la comunicación entre ellos.
• Facilitar la toma de decisiones definiendo un lenguaje común, estableciendo un marco de actuación y una metodología de trabajo que se refleje en las guías de estándares y buenas prácticas.
• Dar soporte a los distintos grupos para garantizar la vitalidad y evolución de las soluciones.
• Establecer políticas y puntos de control para el cumplimento de dichas políticas.
• Garantizar el alineamiento estratégico de la iniciativa entre negocio y tecnología, fomentando la transparencia, la comunicación entre los implicados y elaborando los comités/reuniones necesarios para conseguirlo.
• Son los responsables del registro de las APIs y la calidad de la documentación de las mismas.
• Fomentar el uso de las APIs y actuar como evangelizador de la tecnología siendo responsable de comunicar y formar a la organización en todo lo que engloba esta disciplina.

Referencias

• My Moving Towards a Modern API Lifecycle From POST/CON 2018
• Moving away from centralized SOA governance
• API Team Best Practices: The API Product Manager & the API Architect
• The Value of APIs for Government
• What is API Lifecycle Management?
• API Business Models for the Modern API Economy