Header Ads Widget

Ticker

6/recent/ticker-posts

¿Qué son los cambios importantes y cómo evitarlos?

 

Uno de los aspectos más complicados de ser un proveedor de software es gestionar el cambio. Por un lado, desea evolucionar continuamente su oferta, agregando nuevas funciones y mejorando las antiguas para mantener su ventaja competitiva. Por otro lado, sabe que la continuidad es primordial para sus desarrolladores, por lo que los cambios deberían tener un impacto mínimo en las integraciones existentes.

En cualquier caso, algo que definitivamente debe tener en cuenta es el cambio radical , que puede hacer que las aplicaciones de sus clientes fallen. Especialmente en el mundo de las conexiones API, romper el cambio es una preocupación importante. Entonces, ¿qué constituye exactamente un cambio radical en términos de API web? ¿Y cómo podemos evitarlo?


 

¿Qué es un cambio radical?

Como sugiere el nombre, un cambio importante en una API es cualquier cambio que pueda romper la aplicación de un cliente. Por lo general, los cambios importantes implican modificar o eliminar partes existentes de una API.

Con este último, la eliminación, es inevitable que las aplicaciones se rompan. Si un cliente consume el recurso, campo o estructura eliminados, partes de su aplicación dejarán de funcionar. La medida en que esto realmente "rompe" la aplicación puede variar mucho, desde tener un efecto cosmético menor hasta hacer que la aplicación sea completamente inutilizable; Independientemente, la eliminación todavía se considera un cambio importante.

Es menos probable que la modificación rompa las aplicaciones. Incluso si un cliente está utilizando el recurso, el campo o el punto final que se modifica, existe la posibilidad de que su aplicación continúe funcionando normalmente, según la implementación. Por ejemplo, si una API multimedia pasa de devolver archivos JPEG a PNG, las aplicaciones que también guardan esos tipos de archivos probablemente seguirán funcionando.

Por supuesto, la modificación aún conlleva un riesgo real de romper las aplicaciones del cliente. Dado que el propietario de la API responsable no deja estas cosas al azar, las modificaciones también deben tratarse como cambios importantes.

Ejemplos

Los ejemplos comunes de cambios importantes incluyen:

  • Eliminar un recurso o método
  • Eliminar un campo de respuesta
  • Modificar un URI de recurso o método
  • Modificar un nombre de campo
  • Modificar los parámetros de consulta necesarios
  • Modificar autorización
  • Modificar la limitación de velocidad

¿Qué no es un cambio radical?

Ahora que hemos hablado de lo que es un cambio radical, es posible que se pregunte qué no es . Afortunadamente, la respuesta es bastante sencilla:

En la mayoría de los casos, un cambio que se agrega a una API no es un cambio rotundo.

Este tipo de cambio, llamado cambio aditivo , puede involucrar nuevos recursos o métodos, nuevos campos de respuesta e incluso nuevos parámetros de consulta. Dado que estos cambios no afectan los flujos existentes, no deberían interrumpir las aplicaciones, pero hablaremos de eso en un segundo.

Ejemplos

Algunos ejemplos comunes de cambios aditivos e irreversibles incluyen:

  • Agregar un recurso o método
  • Agregar un campo de respuesta
  • Agregar parámetros de consulta opcionales

Cuando los cambios aditivos rompen las aplicaciones

Como ocurre con todas las grandes reglas, la idea de que los cambios aditivos no pueden romper las aplicaciones tiene sus excepciones.

En primer lugar, agregar requisitos a su API, como esquemas de seguridad obligatorios o requiredparámetros de consulta, es un cambio radical. Para evitar esto, asegúrese de que la interacción con las adiciones que introduzca sea opcional.

Incluso entonces, hay situaciones en las que los propietarios de API pueden agregar y aún romper las aplicaciones de sus clientes, especialmente si esas aplicaciones están mal codificadas. Vea estos ejemplos del ingeniero y bloguero Ben Nadel:

“¿Qué pasa si el consumidor necesita serializar los datos y almacenarlos en una columna de base de datos que tiene un tamaño de carácter limitado? En tal caso, incluso un cambio 'aditivo' podría causar un error inesperado de truncamiento de la base de datos…. O imagine que la respuesta se registra en un archivo. Un aumento en el tamaño de la carga útil de respuesta podría cambiar la velocidad con la que los archivos de registro ocupan espacio en el disco. Esto, a su vez, podría causar problemas si los archivos de registro no se rotan con la suficiente rapidez ".

Hay muchos otros escenarios en los que los datos adicionales pueden hacer que las aplicaciones se rompan. A veces, esto puede implicar paginación, que el consumidor no espera; otras veces, puede implicar tiempos de respuesta incrementados que afectan el flujo de una aplicación.

Prácticas recomendadas para realizar cambios importantes

Si desea cuidar de la mejor manera posible a sus clientes (¡y debería hacerlo!), Existen bastantes prácticas recomendadas que puede adoptar para evitar y mitigar cambios importantes. Comencemos con cómo puede evitarlos, ya que esto siempre es preferible para los desarrolladores:

  1. Pruebe su código para detectar cambios accidentales. Los cambios importantes son particularmente problemáticos si no sabe que están ahí. Afortunadamente, existe una solución fácil para los propietarios de API que se basan en una especificación de OpenAPI : openapi-diff. Esta herramienta de código abierto compara dos especificaciones de OpenAPI (v3) y le alerta si se han realizado cambios importantes (obvios).
  2. Prepara tu documentación para el futuro. Puede ser un cliché, pero la documentación realmente puede ayudarlo a evitar cambios rotos, especialmente los aditivos. Por ejemplo, en las primeras etapas de una plataforma, algunos objetos pueden constar de unos pocos campos. Si sabe que se agregarán muchos más campos en el futuro, puede indicar a los clientes que esperen esto y creen sus aplicaciones en función de ello.
  3. Planifique cuidadosamente su API con anticipación. Una vez más, puede ser obvio, pero la importancia de planificar cuidadosamente sus API no puede subestimarse. Incluso algo tan mundano como nombrar puede resultar en cambios rotundos, o una experiencia de desarrollador persistentemente mala , si se planifica mal.

Desafortunadamente, a menudo hay situaciones en las que su única opción es introducir cambios importantes. Si es así, debe incluir estos cambios en una nueva versión de su API mientras continúa brindando soporte para la versión anterior durante un período de tiempo determinado (generalmente un año). Para reducir el impacto que el control de versiones tiene en los clientes, puede hacer algunas cosas:

  1. Usa encabezados obsoletos . Para darles a los clientes un poco más de tiempo para reaccionar, puede desaprobar funciones antes de eliminarlas o revisarlas por completo. Asegúrese de incluir esta información en el campo de encabezado HTTP obsoleto y sepa que las siguientes dos mejores prácticas aún se aplican.
  2. Establece cronogramas claros . Para minimizar la confusión y fomentar la acción, asegúrese de establecer plazos claros para cuándo se lanzarán nuevas versiones y cuándo dejarán de ser compatibles las versiones anteriores. Aún puede ofrecer cierta indulgencia cuando lleguen fechas importantes, ¡pero los desarrolladores no necesitan saber eso!
  3. Tenga avisos claros . Las nuevas versiones (y las obsoletas) solo son útiles si los clientes las conocen, así que no tema hacerse oír. Coloque avisos claros y en negrita en su portal para desarrolladores, especialmente en las páginas de documentación, y envíe correos electrónicos a los desarrolladores con líneas de asunto precisas.

Romper el cambio rompe corazones

Los cambios importantes generalmente ocurren cuando cambia o elimina una funcionalidad existente, pero incluso pueden aparecer cuando agrega a su API. En cualquier caso, se deben evitar los cambios importantes siempre que sea posible, ya que pueden causar una interrupción significativa a sus clientes. Afortunadamente, existen algunas mejores prácticas que pueden ayudarlo a evitar cambios importantes o, si es necesario, mitigar su impacto.

¿Qué constituye un cambio radical en tu mente? ¿Qué hace su equipo para evitar romper el cambio? ¡Déjanos saber tus pensamientos abajo!

Publicar un comentario

0 Comentarios