Header Ads Widget

Ticker

6/recent/ticker-posts

Métodos para comunicar el cambio de API de manera efectiva

 


La industria de las API prospera con el cambio . A medida que crecen las necesidades del consumidor, también lo hacen las demandas del proveedor de API. En consecuencia, los proveedores se enfrentan a la creciente perspectiva de una constante evolución tecnológica.

Si bien este ciclo de cambio es en gran medida positivo, trae consigo algunos desafíos únicos; Uno de esos desafíos es el de comunicar el cambio a los usuarios desarrolladores. Ya sea que se trate de control de versiones, retiro de endpoints u otros cambios, los usuarios desarrolladores en el panorama moderno de API esperan un marco de tiempo asignado y un método de comunicación mucho más matizado y completamente dirigido.

Hoy, analizaremos algunos de estos métodos de comunicación e identificaremos por qué los enfoques tradicionales de comunicación pasiva, como los que se usan en el control de versiones de API tradicionales, no brindan una respuesta adecuada al problema en cuestión. Analizaremos 6 formas sólidas de comunicar el cambio de API, así como también destacaremos algunas advertencias en diferentes modos de comunicación.

Por qué la comunicación pasiva es un problema

Las API se comunican pasivamente cuando publican cambios sin intentar un aviso público planificado; una organización crea la información y la coloca en una ubicación estática, esperando que los usuarios que quieran tropezar con ella.

Esto es ineficaz por varias razones. Si bien el control de versiones no es en sí mismo una sentencia de muerte para la API, sin un plan de comunicación establecido, puede crear más problemas de los que resuelve. Puede hacer que los usuarios encuentren que su firmware, software y otros elementos no son compatibles con un punto final o recurso previamente configurado. En otras palabras, la comunicación pasiva como único método de gestión del cambio puede resultar fácilmente en cambios rotos y clientes insatisfechos.

La notificación adecuada puede solucionar esto, por supuesto, dando a los usuarios tiempo suficiente para garantizar la configuración, pero la carga del lado del cliente es más compleja de lo que cree. El proceso de verificación de la versión, actualización de credenciales e integración con los nuevos cambios puede resultar en una importante dedicación de tiempo . Cuanta más comunicación pasiva se utilice para abordar estos cambios, mayor importancia se le dará al usuario . En última instancia, se trata de un cambio de responsabilidad inadecuado.

¿Qué podemos hacer, entonces, para que la comunicación de estos cambios sea mejor, más efectiva y, en última instancia, una mejora en la naturaleza básica y central de la comunicación de cambios pasiva basada en versiones?

Lea también: Introducción a las mejores prácticas de control de versiones de API

Definición del consumidor de API

Una de las mejores cosas que podemos hacer a la hora de comunicar el cambio es identificar quién es el usuario de cada uno de nuestros servicios y adoptar un método de comunicación acorde a sus necesidades.

Podemos pensar que las API tienen tres clases de usuarios. Un usuario normal es simplemente el usuario más básico que utiliza las funciones más básicas. Por encima de esto, los superusuarios requieren funciones especializadas y servicios más complejos. Finalmente, los usuarios internos utilizan la API desde un punto de vista interno, ya sea como parte del equipo de desarrollo o como socio comercial que utiliza dichos puntos finales internos.

Una vez que definamos al usuario, podríamos señalarle aspectos específicos del cambio que se adaptan a los microservicios que consumen; esto puede evitar la sobrecarga de notificaciones. Además de las alertas de funciones específicas, conocer los hábitos de los consumidores de API también puede determinar qué canales privilegiar en sus anuncios de comunicación.

Por ejemplo, si el usuario básico promedio utiliza Twitter para interactuar con el equipo de desarrollo, la comunicación adecuada del cambio podría ser tan simple como enviar un breve resumen a través de un Tweet a dichos usuarios. Por otro lado, si ninguno de sus superusuarios o usuarios internos utiliza Twitter, sino que prefiere utilizar el correo electrónico, dicha comunicación debería producirse a través de ese canal.

Para obtener más información, lea: Cómo comprender a su consumidor de API objetivo

6 formas sólidas de comunicar el cambio de API

Ahora que hemos establecido algunas pautas iniciales para comunicar los cambios, veamos algunos métodos de comunicación específicos. No todos estos métodos serán apropiados para todos los casos de uso; como tal, es imperativo que el desarrollador observe su base de usuarios e identifique las mejores opciones específicas para sus necesidades limitadas y dadas.

Registro de cambios

Un método común de comunicación de cambios es un registro de cambios . En esencia, un registro de cambios simplemente sirve como un método de seguimiento a largo plazo de comparación entre varias versiones. Cuando se actualiza una API, cada cambio se indica como una desviación de la versión anterior, y esto sirve como un método para comunicar no solo qué se cambió, sino por qué se cambió.

Sin embargo, para hacer registros de cambios realmente efectivos, debe agregar algunos elementos a la solución tradicional con mucho texto. Una adición clave son los enlaces a registros de cambios anteriores en orden histórico, lo que permite a los usuarios trabajar hacia atrás y contextualizar.

Un registro de cambios debe considerarse un método de comunicación, pero un elemento importante es considerar el método mediante el cual se emite este registro de cambios. Los registros de cambios activos son casi siempre la mejor opción, y se envían activamente a los usuarios que utilizan los servicios proporcionados. Los registros de cambios pasivos, por otro lado, no son fundamentalmente diferentes del enfoque de comunicación de versiones pasivas discutido anteriormente.

Redes sociales

Un excelente método moderno de comunicación es mediante el uso de las redes sociales. Enviar alertas de cambios e incluso usar las redes sociales para responder a las necesidades, quejas y preguntas de los usuarios sobre los cambios puede ser muy eficaz.

Dicho esto, dicha notificación de cambio debe ocupar su propia cuenta de desarrollador, de modo que esta información no se pierda en el resto de su correspondencia social. Esto es especialmente importante cuando los proveedores de API operan en múltiples campos y funciones, como cuando un consultor comercial puede proporcionar una API para un propósito comercial secundario. En esos casos, dicha separación es imperativa.

Sin embargo, si eso no es posible, al menos, cada publicación respectiva en las redes sociales también debe proporcionarse en el formulario de actualización de noticias en una sola página web, para permitir la vinculación de una notificación a otra. En última instancia, las redes sociales pueden ser una herramienta muy poderosa, siempre que se consideren y seleccionen cuidadosamente.

Más sobre gestión de cambios: estrategia de cambio de API

Envío de correo electrónico automatizado

El uso de servicios de correo electrónico automatizados puede comunicar el cambio de manera eficaz al proporcionar un amplio espacio para la notificación y descripción de los cambios. Dicho esto, enviar correos electrónicos puede ser más complicado que otras opciones debido a la naturaleza del envío de correos electrónicos en sí. Los registros de cambios y las redes sociales son fundamentalmente opcionales, lo que significa que el usuario elige participar en dicha comunicación. Sin embargo, el correo electrónico puede ocurrir sin que el usuario elija recibir dicha información.

En consecuencia, no asuma que todos los usuarios querrán una actualización, especialmente si los cambios ocurren a diario. Si no se soluciona este problema, se produciría la misma fatiga de notificación que estamos intentando evitar. Permitir la configuración de suscripción y notificación . Además, proporcione un método adecuado para rechazar dichos correos electrónicos para garantizar el cumplimiento de las mejores prácticas de comunicación.

Portales para desarrolladores y notificación visual

Un gran método para comunicar el cambio es utilizar herramientas centradas en el desarrollador . Algo tan simple como un registro de desarrollo , una especie de blog que documente el desarrollo y las elecciones realizadas a lo largo del ciclo de vida, puede ser extremadamente efectivo. Una parte integral de este tipo de comunicación es el uso de un portal de desarrollo que utiliza algún tipo de representación del progreso del desarrollo para comunicar el cambio.

Mailchimp es un gran ejemplo de este tipo de comunicación. Su metodología utiliza una barra roja que se llena a medida que se completa el desarrollo y proporciona enlaces a los cambios a medida que se presentan. Este tipo de portal de desarrollo es ideal para contextualizar el cambio y el desarrollo a lo largo del tiempo, así como el efecto de cada cambio en todo el sistema.

Mailchimp destaca los cambios de API en la parte superior de las páginas del portal de desarrollo.

Dicho esto, esto no debe usarse como un sistema principal, ya que básicamente es solo una versión más bonita de un registro de cambios estático y pasivo que los usuarios pueden ver al navegar a un sitio.

HyperMedia

Una API RESTful correctamente diseñada también puede cumplir una especie de función de notificación. Hipermedia se ha dicho para ser un requisito previo de una API REST realmente - es una suerte, entonces, que Hipermedia es un requisito previo a la comunicación un cambio efectivo en ese reino también.

Con una configuración adecuada de Hypermedia, se puede pasar un objeto al usuario que no solo notifica a dicho usuario de un cambio, sino que también proporciona un enlace de hipertexto al registro de cambios, a las cuentas de redes sociales, incluso a la nueva documentación del endpoint. Hypermedia sirve como una notificación al usuario tanto de la versión como de los cambios en esa versión, y multiplica los esfuerzos para documentar el cambio a niveles mayores.

Lanzamiento canario

En algunos casos, las diferencias entre cada cambio pueden no ser lo suficientemente marcadas como para justificar la comunicación en los métodos discutidos anteriormente. Canary Release es un ejemplo. En este enfoque, el control de versiones se evita exponiendo gradualmente a los usuarios a la nueva compilación a lo largo del tiempo, presentando una transición más simple, limpia y fluida para los usuarios en cuestión. Desafortunadamente, esto también significa que se requiere la notificación de la versión, pero tal notificación puede no ser apropiada para todos los usuarios.

En estos casos, dichas notificaciones deberían servir como un servicio secundario, en lugar de una advertencia de servicio interrumpido, nueva funcionalidad, etc. - la transición debería ser completamente fluida. El usuario debe estar al tanto de la posibilidad de una nueva versión, pero tal cambio no debería en sí mismo requerir ver el registro de cambios.

Leer más: Uso de Canary Release para facilitar el control de versiones de API

Pensamientos finales

Si bien es tentador ceñirse a lo probado y verdadero, existen muchos métodos más modernos y efectivos que simplemente emitir un número de versión simple o una notificación a través del primer contacto con una API.

Como parte de este enfoque moderno, también debe tenerse en cuenta que una sola metodología tampoco es siempre la mejor opción. Con un conjunto moderno de opciones y una variedad de canales para comunicar el cambio, se puede aprovechar una combinación para coordinar las actualizaciones de muchos grupos de usuarios con contenido de comunicación personalizado apropiado para cada vía y grupo de usuarios que utilice esa vía.

En última instancia, la forma en que uno elige notificar a los usuarios de un cambio puede ser muy variable. Lo que realmente importa no es tanto los detalles específicos de cómo notifica, sino que notifique de una manera útil y adecuada dado su caso de uso específico, su base de usuarios y las advertencias que representa cada situación única. La notificación adecuada es extremadamente importante y puede marcar la diferencia en la experiencia del usuario que cambia drásticamente el flujo de usuarios y la percepción de su API.

¿Cómo se está difundiendo su plataforma sobre el cambio de API? Háganos saber en los comentarios a continuación.

Publicar un comentario

0 Comentarios