Header Ads Widget

Ticker

6/recent/ticker-posts

No olvide estos cinco elementos en su registro de cambios de API

 


Tanto para los desarrolladores como para los entusiastas técnicos, pocas cosas son más emocionantes que una versión de software. Si bien los usuarios cotidianos están acostumbrados a las típicas "mejoras y correcciones de errores", las expectativas de cambios dentro de la comunidad de desarrolladores son mucho mayores. Las API que se mantienen de forma activa son la base de numerosos productos de software. Es absolutamente fundamental que los equipos técnicos tomen una decisión informada antes de hacer clic en "actualizar", ya que los cambios pueden afectar notablemente a los proyectos.

La transparencia del software es vital, ya sea que se trate de API de código abierto, privadas o de socios. Esta guía desglosa la importancia de los elementos centrales del registro de cambios y por qué debería incluirlos.

Números de versión
Comencemos con lo básico: control de versiones . Los números de versión son indicadores de progreso que se pueden escanear fácilmente, ya sean versiones estables, versiones nocturnas u otras ramas de desarrollo. Por ejemplo, es posible que esté familiarizado con el enfoque de control de versiones de Apple para sus productos de software. A las versiones principales se les asigna un aumento de número de versión completo (digamos 14 a 15), las actualizaciones significativas dentro de una rama principal un aumento parcial (15.0 a 15.1) y los parches incrementales un aumento menor (15.1 a 15.1.1).

Los usuarios han llegado a asociar los números de versión con el alcance o el contenido general de una actualización. Una multitud de equipos de desarrollo han adoptado esta estrategia para sus API. Puede que valga la pena "telegrafiar" el contenido de las actualizaciones de su API en función de las asignaciones de versión. Por el contrario, se podría emular el enfoque simplificado Graph API de Facebook , donde la mayoría de las actualizaciones reciben un aumento de número completo. Es importante elegir una convención de numeración coherente que los desarrolladores comprendan con relativa facilidad.

En otras palabras, los números de su versión revelarán lo siguiente :

Grado de cambio , incluido el tamaño, el embalaje general y el impacto de una actualización determinada.
Orden de lanzamiento - o cómo una actualización se alinea con otras cronológicamente
Fecha de lanzamiento : utilizado por Google y otros, un número de versión puede indicar directamente una fecha de lanzamiento.
Un número de versión puede ayudar a transmitir la presencia de funciones, actualizaciones de seguridad y correcciones de errores críticos. Estos patrones pueden ayudar a establecer las expectativas de los usuarios. En consecuencia, es útil hojear un historial de versiones en GitHub o en el sitio de un proveedor al determinar las frecuencias de lanzamiento, y cómo se alinean con el contenido de la actualización. La numeración semántica es esencial en esta búsqueda.

Problemas conocidos y problemas resueltos
Aprovechando las expectativas, es bien sabido que ningún software es perfecto. Los errores y otros problemas a menudo surgen entre las compilaciones; estos pueden trasladarse a versiones posteriores. Para romper cambios en especial, es importante tener en cuenta estos y la forma en que puede afectar a la funcionalidad o compatibilidad.

Además, es común que los desarrolladores de API adjunten soluciones a problemas persistentes. Estos problemas conocidos pueden corresponder a transiciones, al pasar de una tecnología a otra o al reemplazar componentes obsoletos. Pueden decirles a los desarrolladores cómo ajustar su código en consecuencia para preservar la funcionalidad para los usuarios finales. Estas instrucciones ayudan a que los programas dependientes se ejecuten de manera satisfactoria hasta que finalmente lleguen las correcciones. Puede etiquetar cada problema en consecuencia con números de identificación con fines de seguimiento.

Finalmente, hemos resuelto los problemas. Estos fragmentos en el registro de cambios les dicen a los usuarios qué se ha corregido en la compilación actual. Es posible que muchos de estos cambios hayan sido esperados durante mucho tiempo, y es crucial mostrarlos a los desarrolladores de software. Tener en cuenta cualquier problema resuelto también es fundamental para realizar pruebas. Si bien una empresa solo puede replicar ciertos casos de uso y variables a través de pruebas internas, los entornos de producción pueden desencadenar todo tipo de sorpresas. Los desarrolladores pueden reconocer cualquier resolución y verificar que sea efectiva. Luego, pueden enviar comentarios en consecuencia a los desarrolladores de la API.

Nuevas características
Todo el mundo ama las nuevas funciones. Mantienen un producto API fresco, emocionante y satisfacen las solicitudes de los usuarios. Los usuarios de software a menudo equiparan el nivel de innovación de un producto con la introducción de funciones, por lo que permanecer estancado es perjudicial para la adopción de API. Los lanzamientos de funciones pueden cambiar fundamentalmente la forma en que los desarrolladores interactúan con las API. Los usuarios finales también pueden sentir sus efectos más adelante en la cadena.

Además, tenga en cuenta que es posible que algunas de las funciones de su API no sean aparentes. Llamar la atención sobre ellos puede ayudar a descubrirlos y, en general, generar entusiasmo. Naturalmente, la profundidad y el tono de sus notas de lanzamiento pueden variar bastante, desde formales hasta divertidas. La forma en que elija resaltar o "vender" las nuevas funciones puede influir en la tracción que obtienen.

Además, puede optar por tener en cuenta la forma específica POST, GET, PUT, PATCH, y DELETElas llamadas interactuar con ciertos rasgos (o cómo esas interacciones han evolucionado). También podríamos relacionar fácilmente este punto con problemas conocidos y soluciones.

Si bien algunas funciones pueden no tener precedentes a lo largo del ciclo de vida de una API, otras pueden reemplazar completamente las que existían anteriormente. Es importante mencionar esto para establecer expectativas y establecer plazos. Por ejemplo, Facebook menciona lo siguiente sobre la función oEmbed dentro del registro de cambios Graph API v11.0:

El producto oEmbed ha sido reemplazado por una nueva función de lectura oEmbed. Si implementó el producto oEmbed antes del 8 de junio de 2021, tiene hasta el 7 de septiembre de 2021 para completar la revisión de la aplicación para la función de lectura oEmbed. Si no ha sido aprobado para la función de lectura de oEmbed antes del 7 de septiembre de 2021, sus implementaciones de oEmbed no se cargarán.

Cuando las funciones están configuradas para reemplazarse entre sí, algunos cambios importantes pueden ocurrir en una fecha posterior (si no inmediatamente). Los desarrolladores que se preocupan por sus usuarios deben anotar cualquier condición o transición en un lenguaje sencillo, para no causar confusión o sorpresas no deseadas.

Desaprobaciones
Por último, es común que el código, las metodologías y las funciones se retiren durante el ciclo de vida de una API. Esto ocurre a medida que evolucionan los productos y los comportamientos de los usuarios; es indicativo de un desarrollo continuo. Una desaprobación indica efectivamente el final de la vida útil de un componente de la API. Todos los desarrolladores deben explicar cómo las depreciaciones importantes afectarán las configuraciones, la ejecución de código, las solicitudes HTTP y más. Dejar a los desarrolladores en la oscuridad solo causará problemas y frustración.

Es común combinar las desaprobaciones con las recomendaciones de actualización, ya que ahora existirán nuevos protocolos en su lugar. Estos pueden suceder automáticamente durante una actualización. Sin embargo, el desarrollador puede tener la responsabilidad de ajustar su código API y preservar las integraciones. De cualquier manera, los usuarios de la API deben tener un camino claro a seguir para evitar problemas paralizantes. Esto puede existir explícitamente dentro del registro de cambios o vivir dentro de la propia API. Por ejemplo, si el programa de uno reconoce un componente obsoleto, su API podría activar una alerta para sus usuarios para mantenerlos al tanto de la situación.

Al igual que con los problemas conocidos, algunas obsoletas también tienen sus propias soluciones.


Publicar un comentario

0 Comentarios