Header Ads Widget

Ticker

6/recent/ticker-posts

Introducción a las mejores prácticas de control de versiones de API


 El cambio es inevitable y el crecimiento es algo bueno. Cuando su API haya alcanzado el punto de expandirse más allá de su intención y capacidad originales, es hora de considerar la próxima versión .

Ya sea que la próxima iteración sea un aumento de la versión de números enteros o simplemente una expansión de funciones, es importante considerar los pros y los contras de cómo se lo informa a sus desarrolladores. Muy diferente al control de versiones de software tradicional, el control de versiones de API puede tener implicaciones complejas para los productos que lo utilizan en sentido descendente.

Los grandes cambios en la versión generalmente indican un hito significativo en el código base de la API. Declara un cambio significativo en los requisitos de consumo e implementación de API. Las adiciones de funciones que no necesariamente cambian las llamadas existentes son parte del crecimiento orgánico de un producto y no están sujetas a las mismas consideraciones.

Una vez que empiece a quitar cosas, o a cambiar drásticamente lo que está en su lugar, es hora de considerar otra versión. A menudo, estas nuevas versiones se convierten en productos completamente nuevos. Aunque comparten una ascendencia común, las nuevas versiones de API heredadas requieren una reflexión cuidadosa en su implementación.

Para obtener información más avanzada sobre el control de versiones de API, lea Estrategia de cambio de API o ¿Cuál es la diferencia entre el control de versiones y las API de revisión?

Control de versiones de API tradicional: n + 1

Los cambios de servicio que pueden justificar una nueva versión incluyen: eliminar una operación, cambiar el nombre de una operación, cambios en los parámetros de la operación que cambian los tipos de datos o el orden y cambios estructurales complejos del tipo de datos.

Un incremento de versión también puede indicar cambios significativos en los requisitos de consumo de API. También puede anunciar un cambio radical en los recursos subyacentes que ofrece la API. En cualquier caso, los productos y plataformas que dependen de una API para la funcionalidad principal pueden necesitar un refactor de código para adaptarse.

Eso puede requerir mucho tiempo y recursos, por lo que un enfoque sensato y bien documentado para el control de versiones de URI es crucial para múltiples partes interesadas. El control de versiones puede ser un tema controvertido dentro de los equipos y, a menudo, la primera pregunta es si se debe usar.

Un URI para gobernarlos a todos

Una escuela de pensamiento es centrarse en una URI que no cambia con un solo conjunto de criterios de consumo. Si se cambia la estructura de la API, se alteran los recursos o se modifica el conjunto de parámetros, el producto se vuelve a lanzar con el mismo URI. Esto empuja la obligación de refactorizar el código a los desarrolladores posteriores.

Los defensores de este enfoque dejan de mencionar a Tim Berners-Lee. A menudo se le cita diciendo  "una URI genial es aquella que no cambia". En contexto, esa cita tenía la intención de abordar la incipiente Internet que dependía de los hipervínculos dentro de las páginas web para perdurar. La red conectada , en ese momento, era una serie de nodos de información.

Sin embargo, el mundo ha cambiado y trabajamos con una matriz interconectada de servicios web potentes y con muchos recursos. Una vez que los servicios se generalizaron, los primeros enfoques fueron similares a los números de versión de software. Pero el software autónomo tiene implicaciones posteriores muy diferentes a las de los servicios web interdependientes.

IBM aborda esto en sus propias " Mejores prácticas para servicios web ":

“El manejo correcto del control de versiones de API ha sido uno de los problemas más difíciles que enfrentan los desarrolladores de sistemas distribuidos. Se han propuesto varios esquemas, que van desde el enfoque de laissez faire adoptado por CORBA (Common Object Request Broker Architecture) hasta los esquemas más estrictos utilizados en DCOM (Distributed Component Object Model). Con la llegada de los servicios web, hay algunas características nuevas que puede aprovechar y que pueden ayudar a aliviar el problema, pero el hecho brutal del asunto es que el control de versiones no se ha integrado en la arquitectura de servicios web ".

Lo que constituye las "mejores prácticas" ha evolucionado con el tiempo y está determinado por las elecciones de los proveedores para sus propios productos, no necesariamente de ningún órgano de gobierno externo. Entonces, cuando se trata de elegir un enfoque para el control de versiones, existe una amplia variedad de prácticas.

Sobre compatibilidad con versiones anteriores

Otra consideración es la compatibilidad con versiones anteriores . Para muchos proveedores de API de recursos web, esta es la consideración principal. El mantenimiento de varias versiones de una API que consume muchos recursos puede suponer una gran pérdida de tiempo y concentración de los equipos de ingeniería. También puede introducir problemas de estabilidad a largo plazo en los servicios que se han trasladado a arquitecturas más modernas.

Para muchos, presentar una nueva versión que cambia sustancialmente una API es, de hecho, lanzar un servicio completamente nuevo. Tratarlo como un producto nuevo , con nueva documentación , acuerdos de nivel de servicio, cambios de acceso de nivel, etc., puede tener importantes implicaciones comerciales. Más de una pizarra se ha llenado de cifras que debaten si un cambio es una elección de ingeniería o un cambio empresarial .

Una vez que se ha tomado la decisión de introducir una nueva versión, es útil buscar en proveedores establecidos soluciones probadas en batalla.

Relacionado: Las 5 principales razones comerciales para el retiro de API

Ejemplos de control de versiones en la naturaleza

¿Qué podemos aprender de las prácticas de control de versiones de los proveedores de API web establecidos? Google sale de la puerta con una afirmación contundente de control de versiones numeradas: "Las API en red deben usar el control de versiones semántico ". No hay mucho margen de maniobra allí. También tienen un sistema igualmente sencillo. Los indicadores de versión utilizan el formulario v.MAJOR.MINOR.PATCH .

Twilio usa una marca de tiempo en la URL, en lugar de un número de versión. Salesforce opta por vXX.X en el medio de la URL. Facebook apuesta por anteponer la versión a la ruta del punto final. La versión es en realidad opcional, y las solicitudes de versión no especificadas se envían a la versión más antigua disponible.

Tenga en cuenta que la granularidad que ofrece vX.X suele estar destinada al desarrollo y no necesariamente a la producción. Primero consulte los documentos, pero es una buena idea optar por referencias de números ordinales en el código de producción.

La gente de DevOps puede estar familiarizada con el enfoque UDDI y WDSL para las definiciones de versión. Las soluciones HTTP son mucho más populares, pero hay soporte para este tipo de enfoque. Implica una solicitud de versión a través de un intercambio XML para obtener la versión adecuada.

Empresas megalíticas como Microsoft, IBM y Oracle tienen referencias a este método en parte de su documentación. Aunque, las indicaciones de la versión HTTP se aceptan en muchas divisiones y productos.

La red de citas Badoo opta por el control de versiones continuo , donde se agregan funciones y los puntos finales permanecen iguales. Los clientes heredados pueden usar campos antiguos y los clientes nuevos usan campos agregados. Las solicitudes de API son transaccionales, con una llamada de solicitud de función realizada y una lista de opciones disponibles devuelta. Las verificaciones de características pueden servir como una especie de solicitud estatal.

El libro de estilo de la API tiene algunas rutas más para explorar sobre el control de versiones. Sin un conjunto codificado de especificaciones, las empresas continúan explorando diferentes opciones.

Versión con aceptar encabezado

Una alternativa común a los parámetros de ruta son los intercambios de encabezados . Pueden ser más detallados sobre la respuesta esperada y generalmente se incluyen de todos modos para una solicitud HTTP. Tener un enfoque de encabezado específico de recurso permite incluir otros parámetros (como almacenamiento en caché, compresión y negociación de contenido ).

Los proveedores de API a menudo comunican los criterios y las limitaciones de los recursos en su respuesta, por lo que los desarrolladores deberán examinar el intercambio de encabezados de todos modos. Además de los códigos de respuesta, las respuestas de encabezado comunes incluyen límites de límite de velocidad , mensajes de error específicos , datos basados ​​en el tiempo y más.

Un valor atípico inteligente es el uso de tipos MIME para incluir un indicador de versión. Los proveedores de API registran estos tipos MIME en su backend y luego los usuarios incluyen los encabezados Accept y Content-type . IETF legitimó este enfoque en RFC4627 . Si bien esto funciona, los desarrolladores que elijan este enfoque inevitablemente terminarán explicando su elección a los tipos de administración que afirman, "pero no funciona en formularios HTML, entonces, ¿por qué quiere hacerlo de esa manera?"

Accept: application/pre.company.app-v1+json
Content-Type: application/pre.company.app-v1+json

El debate sobre la implementación es profundo y continuará. Por lo tanto, los desarrolladores y proveedores deberán tomar decisiones en función de sus necesidades específicas. En general, el enfoque más común es una combinación de parámetros de URI y criterios de encabezado . Las API aceptan solicitudes de URI con parámetros y luego devuelven una carga útil con códigos de respuesta adecuados y (con suerte) metadatos detallados en el encabezado de la respuesta.

Lo que constituye un código de respuesta adecuado es algo que los ingenieros debatirán con alegría y en voz alta en las horas felices de la empresa. Pero aquí hay algunas respuestas negativas útiles que son lo suficientemente detalladas como para ser útiles en el futuro.

400: BAD_REQUEST: ApiVersionUnspecified: An API version is required, but was not specified
400: BAD_REQUEST: InvalidApiVersion: An API version was specified, but it is invalid
400: BAD_REQUEST: AmbiguousApiVersion: An API version was specified multiple times with different values
400, 405: BAD_REQUEST, METHOD_NOT_ALLOWED: UnsupportedApiVersion: The specified API version is not supported
301: MOVED_PERMANENTLY: movedPermanently: This request and future requests for the same operation have to be sent to the URL specified in the Location header of this response instead of to the URL to which this request was sent
410: GONE: deleted: The request failed because the resource associated with the request has been deleted
299: OK: Warning: "Deprecated API"
Para obtener más información sobre las respuestas de error, lea: Mejores prácticas para el manejo de errores de API

Los motivos comerciales dirigirán las opciones de versiones

De alguna manera, los aspectos técnicos del control de versiones son los más fáciles de resolver. El verdadero debate se reduce a las necesidades del producto, las preocupaciones comerciales y los planes futuros. Los requisitos para admitir múltiples versiones de una API pueden ser muy altos en términos de soporte de ingeniería, recursos de backend y ancho de banda simple.

Además, para que se haga bien, una nueva versión necesita documentación completa para realizar la transición con éxito. Dado que la documentación actualizada a menudo es baja en las prioridades de las empresas de rápido movimiento, puede terminar lanzándose mal como una mezcla de documentación antigua y nueva. Una mala documentación puede generar grandes costos en tiempo y dinero.

La principal conclusión aquí es que el control de versiones es una  conversación multifacética . No es solo un problema técnico. Los efectos posteriores y los costos heredados pueden ser sustanciales y todo el proceso debe estar bien pensado para un crecimiento efectivo.

Publicar un comentario

0 Comentarios