Header Ads Widget

Ticker

6/recent/ticker-posts

Estrategia de cambio de API


 Algunas personas, cuando se enfrentan a un problema, piensan "Lo sé, usaré el control de versiones". Ahora tienen problemas con la 2.1.0.

Brandon Byers

Versionado de software

Si su software tiene un esquema de versiones difuso o aparentemente aleatorio, o ningún número de versión aparente, probablemente estará de acuerdo en que trabajar con él puede ser una pesadilla.

Si esta es tu realidad, probablemente estés lidiando con preguntas como: ¿Es compatible con la versión anterior? ¿Hay alguna nueva funcionalidad importante que deba conocer? ¿Por qué parece ser una actualización aunque el número de versión no ha cambiado? Sin respuestas claras y sencillas, estas preguntas pueden provocar dolores de cabeza y pérdida del sueño.

Los esquemas de control de versiones, como el control de versiones semántico, son aclamados por los profesionales del software por estar claramente definidos e intuitivos. Tener un buen esquema de control de versiones facilita la vida de todos.

Durante más de 60 años, al menos desde que Fortran II estuvo disponible en 1958 , la disciplina del control de versiones de software ha estado arraigada en la cultura de desarrollo de software. Tener software sin un número de versión o un nombre de versión es casi impensable. El control de versiones de software como fenómeno es tan omnipresente que incluso las cosas que no son software, como PR 2.0 , gov2.0 e Tax 2.0 , tienen números de "versión".

Como las API son software, la mayoría de las API también tienen números de versión. Para las bibliotecas que están vinculadas estáticamente en tiempo de compilación, esto tiene mucho sentido. Desarrolla su aplicación cliente de acuerdo con una API claramente definida, enlaza con el número de versión de la API con la que desarrolló y tiene la confianza de que la integración funcionará hasta que actualice la biblioteca.

El control de versiones de la API web tiene preocupaciones únicas

API, abreviatura de Application Programming Interface , es un conjunto de métodos de comunicación claramente definidos entre varios componentes de software. Aunque generalmente se asocia con bibliotecas de software, marcos y sistemas operativos, "API" también se utiliza para describir interfaces programables a través de los límites de la red, como llamadas a procedimientos remotos y lo más importante; API web .

Dado que las API web son aparentemente "solo API en la web", la disciplina de control de versiones de las API web también se ha convertido en la norma. Pero hay una diferencia importante entre las API web y la API de una biblioteca de software: las API web no están vinculadas estáticamente en el momento de la compilación . Dado que las API web están alojadas en un servidor, ese servidor debe preservar la compatibilidad con versiones anteriores mientras se use una versión determinada de la API.

Las bibliotecas de software vinculadas estáticamente no tienen esta situación. En el caso del software vinculado estáticamente, el hecho de que haya vinculado la versión 1.0 de una biblioteca no obliga a los responsables de esa biblioteca a admitir la versión 1.0 de ninguna manera. El uso de v1.0 no genera ningún costo para los encargados de mantenimiento de la biblioteca. Los mantenedores pueden eliminar cada línea de código de la que depende de su repositorio de código fuente sin causar ningún daño o rotura. En la misma línea, cuando se lanza v2.0, eso no lo obliga a actualizar. La versión v2.0 del mantenedor de la biblioteca no implica ningún costo para usted. Puede seguir usando la v1.0 durante el tiempo que desee.

Sin embargo, este mundo de dualidad desacoplada no existe para las API web . A medida que las API web evolucionan, cada versión anterior debe mantenerse activamente durante el tiempo que el cliente utilice esa versión de la API web Las API web pueden ser servicios web distribuidos globalmente, adaptándose dinámicamente a sus clientes, cada uno potencialmente integrado con una versión diferente de la definición de API web. Con todos estos rasgos únicos, sus diferencias comienzan a superar significativamente su parecido con las API de biblioteca de software vinculadas estáticamente.

Las API web son más similares a los sitios web

Tanto las API web como las API de bibliotecas estáticas son software, pero todo, desde cómo se desarrollan e implementan hasta cómo se alojan y sirven, es completamente diferente. ¿Quizás todas estas diferencias justifican una perspectiva diferente sobre cómo se versionan también?

En muchos sentidos, una API web tiene más en común con un sitio web que con una biblioteca de software vinculada estáticamente. ¿Y cuándo fue la última vez que vio un sitio web con un número de versión? Cuando realiza un cambio incompatible hacia atrás en su API, ¿alguna vez ha considerado el hecho de que es posible que no esté creando una nueva versión de la misma API, sino una API completamente nueva? Como expresó Roy Fielding en su entrevista de 2014 con Mike Amundsen :

Lo que está creando no es una nueva versión de la API, sino un nuevo sistema con una nueva marca. En la Web, lo llamamos un nuevo sitio web. Los sitios web no vienen con números de versión adjuntos porque nunca es necesario. Tampoco debería hacerlo una API RESTful. Una API RESTful es solo un sitio web para clientes con un vocabulario limitado .

Roy Fielding

Los costos del control de versiones

Como el código que culmina en una versión anterior de una API web no se puede eliminar sin romper los clientes, la existencia de ese código tiene un costo . Hay un mayor costo de mantenimiento , porque una base de código versionada es una base de código más grande. Cada versión de su API debe ser desarrollada, parcheada, documentada e implementada de forma independiente. El control de versiones de API de amplio espectro afectará incluso a los recursos que no han cambiado, creando una superficie de API exponencialmente más grande para mantener que una estrategia más detallada.

Si todas las versiones comparten la misma base de código, los desarrolladores deben considerar todas las versiones al tocar cualquier parte del código, lo que dificulta la comprensión del código Esto puede causar errores y ralentizar el desarrollo. Todo esto conduce a desarrolladores descontentos, menos productivos y menos comprometidos . La moral negativa puede tener un costo enorme si no se aborda.

Sin embargo, hay un costo más concreto y medible que perder la fe del desarrollador. En 2013, Jacques Dubray escribió un artículo que agrupa las estrategias de control de versiones de API web en tres categorías diferentes (nudo, punto a punto y compatible) y una fórmula sobre cómo medir el costo a lo largo del tiempo en cada categoría. Lo que Dubray descubrió fue que el control de versiones punto a punto , que es la estrategia empleada por la mayoría de los desarrolladores de API web en la actualidad, es un 45% más costoso con 4 versiones de API diferentes que una estrategia de control de versiones compatible . Si bien el control de versiones compatible tiene un costo inicial más alto, con el tiempo, proporciona grandes ahorros de costos.

Reutilizado del artículo original de Jacques Dubray. Léalo para obtener una investigación exhaustiva sobre los tres métodos principales de control de versiones de API.

Dado que los números de versión ocultan el hecho de que la nueva API no es compatible con las características de la anterior, hay pocos incentivos para descubrir cómo lidiar con los cambios importantes, además de acuñar un nuevo número de versión. Y por la misma razón, no hay ningún incentivo para encontrar respuestas a preguntas como cómo se notifica a los clientes sobre los cambios, cómo se les incentiva a actualizar o cómo medimos qué funciones están usando los clientes. Y como la mayoría de los desarrolladores experimentados saben, cuanto más pospongamos preguntas como estas, más caras se vuelven de responder. Por lo tanto, deberíamos intentar encontrar una respuesta antes que tarde.

Un cambio de estrategia

En su excelente publicación de blog sobre gestión de cambios de API , Zdenek Nemec escribe:

El control de versiones de una API es como tener tu edad a tu nombre. Sí, estoy hablando contigo John32Emmanuel46Y luego viene la falacia de los recursos "anidados": si el recurso John32/john32) tiene un recurso anidado child/john32/child), ¿el childrecurso también es de la versión 32? ¿O es un childcuándo Johnestaba en la versión 32? ¿Qué pasa si las childversiones están cambiando independientemente de John32?

Zdenek Nemec

Debido a los problemas señalados por Nemec y en este artículo hasta ahora, un eco y una extensión de la propuesta de Nemec sería, por lo tanto, que deseche su estrategia simplista de versionado, porque como escribe Ben Morris ; el número de versión en sí mismo es una pista falsa. En lugar de una estrategia de control de versiones , debería tener una estrategia de cambio .

Una estrategia de cambio abarca la estrategia de versiones compatibles mencionada anteriormente, siendo siempre compatible con versiones anteriores sin duplicaciones innecesarias. En consecuencia , también se incorporará el principio de robustez, lo que le brindará una base sólida para introducir cambios en su API. Para implementar una estrategia de cambio, debe poder responder las siguientes cinco preguntas:

  1. ¿Qué versión?
  2. ¿Cuáles son las reglas de extensión?
  3. ¿Cómo introducimos cambios importantes?
  4. ¿Cómo monitoreamos el uso de funciones?
  5. ¿Cuál es nuestro plan de comunicación?

1. ¿Qué versión?

Al describir sus teorías de gestión de cambios de API, Nemec responde a esta pregunta de la siguiente manera:

  • El cliente tiene una versión
  • El formato del mensaje tiene una versión
  • La implementación de API (servidor) tiene una versión
  • La documentación (descripción de la API) tiene una versión
  • Los recursos no tienen una versión
  • Las relaciones entre recursos no tienen versión
  • La API en sí no tiene una versión

2. ¿Cuáles son las reglas de extensión?

Nemec también tiene una respuesta para esta pregunta, repetida por brevedad:

  1. No debes quitar nada
  2. No debe cambiar las reglas de procesamiento
  3. No debe hacer que las cosas opcionales sean necesarias
  4. Todo lo que agregue debe ser opcional

Esta lista puede cambiar si su API utiliza hipermedia , en cuyo caso los puntos 3 y 4 pueden eludirse. Al agregar valores predeterminados (piense <input type="hidden">) en el formulario que describe la solicitud, un cliente que desconozca las propiedades nuevas y requeridas simplemente pasará felizmente los valores predeterminados en la solicitud.

3. ¿Cómo introducimos cambios importantes?

Nemec también tiene una respuesta para esta pregunta, nuevamente por brevedad; Si un cambio a cualquiera de los siguientes viola las reglas de extensión enumeradas anteriormente, simplemente necesita crear un nuevo recurso:

  • Identificador de recurso (el URI), incluidos los parámetros de consulta y su semántica.
  • Metadatos de recursos (como los encabezados HTTP).
  • Campos de datos de recursos (como el cuerpo HTTP) y su semántica.
  • Acciones que ofrece el recurso (por ejemplo, métodos HTTP disponibles).
  • Relaciones con otros recursos (por ejemplo, enlaces).

Si el formato del mensaje cambia, puede utilizar la negociación de contenido para ofrecer la nueva versión a los nuevos clientes y la versión anterior a los antiguos.

4. ¿Cómo monitoreamos el uso de funciones?

Dado que las bibliotecas de software vinculadas estáticamente no tienen un componente de servidor, es imposible saber qué partes de la API que expone están en uso y cuáles no. Dado que las API web tienen un componente de servidor, es posible y realmente inteligente usar esa ventaja para monitorear qué características de su API están en uso.

El monitoreo es información útil para el lado comercial de su organización para priorizar el tiempo dedicado a agregar y mantener cada característica. Pero es información crucial tener cuando se considera la desaprobación de los puntos finales de API.

Los registros del servidor HTTP son una fuente de información excelente y de fácil acceso sobre el uso de funciones en su API, especialmente si usa hipermedia de manera extensiva, porque tendrá más enlaces y recursos en su API, brindándole más detalles sobre lo que está sucediendo. Cuantos más recursos, más información.

Como los registros predeterminados del servidor HTTP solo contienen el URI de la solicitud, algunos encabezados, el código de estado de respuesta y la dirección IP del cliente, en algún momento serán demasiado superficiales para brindarle la información rica que necesita para tomar decisiones acertadas sobre el futuro de su API. Agregar registros personalizados a través de infraestructura como proxies inversos, software de administración de API o declaraciones de registro simples en su código le proporcionará toda la información que desea.

5. ¿Cuál es nuestro plan de comunicación?

La última pregunta de su estrategia de cambio se relaciona con cómo se comunica con los clientes de su API. Cuando cambie su API, debe tener un plan claro sobre cómo comunicar el cambio.

Cada empresa, API y cliente es diferente, por lo que debe encontrar un método de comunicación que funcione para usted. Puede ser cualquier cosa, desde un boletín, un canal público de Slack, un panel que el cliente ve regularmente, la documentación de la API u otros recursos.

Independientemente de su método, es esencial tener un plan para comunicar nuevas funciones y cambios importantes con los clientes de API. Algo tan simple como las notificaciones por correo electrónico, sin importar cuán obvio y mundano pueda parecer, es imperativo para la comunicación directa para evitar problemas de última hora.

Tenga cuidado con el cambio de API: ¡No permita que los cambios de API lo golpeen como un tren de carga!

Gestión del cambio en la práctica

Ahora que la teoría debería estar bien establecida, ¿cómo funciona la gestión del cambio en la práctica? Tomemos una solicitud de API ficticia como ejemplo:

POST /nordic-apis/2018 HTTP/1.1
Content-Type: application/json

{
  "aquire": "Knowledge",
  "from":   "Nordic APIs Platform Summit",
  "when":   "2018-10-22"
}

Imagínese que esta solicitud de API ha estado disponible durante algunos meses y ahora tiene cientos de clientes activos. Entonces nota el error tipográfico: aquirefalta un cqué hacemos? ¡Pánico! No, cálmate. ¡Cambia de estrategia al rescate!

  1. Agregue soporte para la ortografía correcta de adquirir a la API.
  2. Corrija la ortografía en la documentación. La ortografía fija se puede agregar en lugar del error tipográfico o como un nuevo campo, marcando el anterior como obsoleto.
  3. Notifique a los clientes del error tipográfico y que deben actualizar su software de cliente.
  4. Agregue el monitoreo del uso del campo de error tipográfico.
  5. El tiempo pasa
  6. Notifique a los clientes que aún utilizan el campo de error tipográfico.
  7. Pasa más tiempo
  8. Incentivar a los clientes que siguen utilizando el campo de error tipográfico
    1. Con dinero
    2. Plan de actualización
    3. Productos gratis
    4. Lo que sea
    5. El punto aquí es que mantener el código antiguo cuesta dinero.
    6. Y ese dinero es mejor gastarlo en hacer feliz a su cliente que a sus desarrolladores infelices.
  9. Por último, podemos eliminar el campo de error tipográfico de la API.
  10. Hacer el código esbelto y felices tanto a los clientes como a los desarrolladores

Reflexiones finales sobre la estrategia de cambio de API inteligente

Las API web son inherentemente únicas y funcionan más como sitios web que como una API de biblioteca estática típica. Por lo tanto, antes de diseñar sus API con la mentalidad de romper el cambio, considere el impacto en el ecosistema del cliente. En lugar de una estrategia tradicional de control de versiones punto a punto, el control de versiones compatible puede ayudar a evitar perder la fe del desarrollador y ser utilizado para mantener técnicas de desarrollo eficientes.

Para resumir, considere los cinco aspectos de la gestión inteligente de cambios de API: sepa qué está versionando, establezca reglas para extender los recursos, intente crear nuevos recursos en lugar de introducir cambios importantes, monitoree el uso de funciones y tenga un plan de comunicación con los consumidores de su API. Con las respuestas a estas difíciles preguntas, estará listo para escalar su ecosistema de API con confianza.

Hay muchas opiniones sobre el tema del control de versiones, y nos encantaría escuchar la tuya. ¿Qué piensa de esta estrategia de cambio propuesta? ¿Ha adoptado una técnica similar en su API? Háganos saber en los comentarios a continuación.

Recursos:

  • Toboganes, Asbjørn Ulsberg
  • Schrödingerver de K. Scott Allen
  • Comprender los costos de versionar una API (o un servicio), Jacques Dubray

Publicar un comentario

0 Comentarios