El contenido del siguiente artículo proviene de algún contenido compilado cuando estaba trabajando en la interfaz API antes, lo grabaré y lo compartiré.
En los primeros días de HTTP y HTML, existía la regla de que cualquier navegador que encontrara un elemento o atributo de elemento no reconocido debía actuar como si la etiqueta no existiera. Esto hace posible actualizar rápidamente la funcionalidad de HTML sin aumentar la "destructibilidad" de la aplicación cliente HTML (navegador). (Nota: consulte la charla de Bert Bos de 2001 sobre "W3C, XML y estandarización " para obtener información sobre el diseño temprano de HTTP/HTML).
Todos los ejemplos similares se remontan a una regla básica que guía la creación de la mayoría de los estándares de Internet. El "principio de robustez " propuesto por Jon Postel en 1980 :
" Sé conservador en lo que haces, sé liberal en lo que aceptas de los demás ".
La primera regla para gestionar adecuadamente los cambios a largo plazo en su API es no realizar cambios importantes en producción . La razón es simple: una vez que publicas tu API y la gente comienza a usarla, la interfaz es una promesa. Y romper esa promesa podría significar perder clientes. Como dijo Werner Vogels de Amazon: "Las API son para siempre". Dijo en una publicación de blog de 2016 ,
"[En Amazon] sabemos que diseñar una API es una tarea muy importante porque sólo tenemos una oportunidad de hacerlo bien".
Tres reglas para la compatibilidad con versiones anteriores de las interfaces API
Existen algunas reglas de implementación simples que puede utilizar para reducir la probabilidad de introducir cambios disruptivos en su ecosistema API. Es importante que esto forme parte de sus prácticas de revisión y diseño de API si desea administrar con éxito sus API a largo plazo.
Regla número uno: no te lleves nada.
La primera regla es que una vez que publicas una API, no puedes quitarle nada. No puedes quitar una URL prometida, un parámetro de entrada o un punto de datos de salida . Incluso si les dice a los desarrolladores en su documentación que ciertos elementos de su API pueden desaparecer o cambiar, aún así no podrá hacerlo. Porque, bueno, desarrolladores.
La verdad de esta primera regla se explica en lo que se conoce como “ Ley de Hirum ” o “Ley de Dependencia Implícita”:
"Con un número suficiente de usuarios de API, no importa lo que prometas en el contrato: alguien confiará en todo el comportamiento observable de tu sistema." - Hyrum Wright, ingeniero de software empleado en Google.
Esto también funciona para valores de enumeración. Si tiene un campo llamado estado y registra que tiene cinco valores posibles, no podrá publicar una actualización en la API más adelante cuando el estado solo tenga cuatro valores posibles.
Regla dos: no cambies el significado de nada.
La segunda regla establece que no puedes cambiar el significado de los elementos existentes en tu API . Si el parámetro de recuento en su declaración de filtro de promesa se refiere a "número de usuarios", entonces no podrá cambiar el mismo parámetro a "número de páginas" más adelante.
Cambiar el significado de algo tiene el mismo efecto que quitárselo y sustituirlo por otra cosa. Ese es un cambio radical y un abandono de su juramento hipocrático a la API.
Regla 3: todas las funciones nuevas son opcionales.
La tercera regla es que cualquier funcionalidad nueva (URL, parámetros de entrada y parámetros de salida) debe considerarse opcional. Si su operación addCustomer tomó cuatro parámetros requeridos en la versión original, no puede agregar un quinto parámetro requerido nuevo. Nuevamente, esto esencialmente elimina el antiguo método addCustomer y lo reemplaza con una versión no compatible con versiones anteriores de addCustomer.
Por supuesto, hay situaciones en las que no tienes más remedio que introducir un cambio radical. Tal vez su equipo cometió un error y la API expuso información de identificación personal, o algunas regulaciones cambiaron y ya no se le permite aceptar ni compartir datos, etc. Cuando esto sucede, es hora de quitarse las puntas abiertas. Porque una nueva "versión" de una API es en realidad una bifurcación fatal (en términos de software).
Bifurcar es un término bastante conocido en ingeniería de software. Se remonta a discusiones en línea a través de Usenet a principios de la década de 1980 y se refiere a la creación de una rama fuera del tronco de un proyecto. La suposición era que una vez que se bifurcaba, ya no esperaba volver a fusionarse con el tronco. Si bien hoy en día utilizamos con frecuencia troncos, ramas y fusiones en la ingeniería de software, las API tienden a "permanecer bifurcadas" con el tiempo y rara vez se vuelven a fusionar.
Si sabe que necesita introducir un cambio importante, bifurque su API y publíquela en un nuevo espacio de URL. Llámelo "versión" si lo desea. Pero todavía no eres James Bond, así que ten en cuenta que lanzar una nueva versión no significa que puedas acabar con la anterior. En lugar de eso, debes ejecutarlos uno al lado del otro por un tiempo. Esto evita toda la situación del "dedo medio" que mencionamos anteriormente.
Con las API en paralelo, los consumidores de API pueden continuar usando su versión actual de API hasta que estén listos para actualizar en algún momento en el futuro: su propio cronograma, no el suyo.
Salesforce es una empresa que sabe muy bien cómo bifurcar API para divertirse y obtener ganancias. Tienen la costumbre de lanzar una nueva versión de la API tres veces al año. Su API de primavera de 2021 es la versión 51. La última vez que lo verifiqué, son compatibles con todas las versiones anteriores, desde la primavera de 2014 (¡también conocida como v30!). Sí, Salesforce admite 20 versiones anteriores, una al lado de la otra.
El defensor del código abierto Eric S. Raymond asocia las "bifurcaciones" con eventos trágicos o costosos. La creación de una bifurcación de software generalmente indica una división irresoluble y significa mucha duplicación de esfuerzos. Y, como vimos con el modelo de Salesforce, lo mismo ocurre en el mundo de las API.
Si trabaja en la publicación de cambios importantes, también debe trabajar en versiones paralelas, documentación, soporte en línea, etc.
