Header Ads Widget

Ticker

6/recent/ticker-posts

Todo lo que necesita saber sobre el control de versiones de API


Las API existen en una extraña dualidad. Por un lado, está creando un producto digital para que los desarrolladores de software lo integren. Sin embargo, su producto también son los datos en sí mismos y el acceso a ellos. Con tantos desarrolladores que dependen de una versión estable del servicio, realizar cambios en una API podría generar problemas rápidamente. Con el software tradicional, los errores generalmente se corrigen entre versiones. Sin embargo, con las API, los diseñadores a menudo no pueden darse ese lujo.

El control de versiones de API es la forma de lidiar con esta contradicción. Una estrategia de control de versiones de API adecuada garantiza que una versión de API siga siendo funcional cuando se realizan cambios en el código. También significa que los consumidores de API que utilizan versiones anteriores de la API no experimentarán ningún cambio importante . Al comunicar el cambio de manera efectiva, los consumidores tienen mucho tiempo para actualizar sus integraciones en consecuencia.

Hemos elaborado una guía para el control de versiones de API. Presentaremos cómo los diseñadores de API pueden crear versiones de sus API y ofreceremos algunos ejemplos de por qué el control de versiones de API es una buena idea. ¡También veremos cuándo el control de versiones de API no es una buena idea!

Cuándo crear una versión de API

En general, es bastante corta y seco cuando para crear una nueva versión de la API - cualquier momento cambia de API. Sin embargo, hay más que eso.

Más específicamente, el control de versiones de API debería ocurrir cada vez que usted:

  • Cambie los campos o el enrutamiento después de que se publique una API.
  • Cambie las estructuras de carga útil, como cambiar una variable de un número entero a flotante, por ejemplo.
  • Elimine los puntos finales para corregir el diseño o la implementación deficiente de HTTP.

Si necesita cambiar alguno de estos después de que su API ya se haya lanzado, podría ser el momento de lanzar una nueva versión de API. De esta manera, los productos digitales de sus clientes existentes no se romperán ni se interrumpirán.

Puede haber otras razones por las que también podría querer crear una versión de API; por ejemplo, agregar puntos finales o nuevos parámetros a las respuestas también podría requerir una revisión . Sin embargo, es posible que estos cambios no justifiquen una versión completamente nueva. Es probable que una pequeña actualización sea suficiente. Independientemente, realizar un seguimiento de las revisiones menores podría ayudar a solucionar los problemas técnicos de un cliente.

Hacer cambios en una API existente significa evolucionar el contrato de API. Antes de profundizar en las diferentes formas de crear una versión de API, consideremos el contrato de API por un momento.

¿Qué es el contrato API?

El contrato de API es el acuerdo entre el productor y el consumidor de API. Detalla lo que el consumidor puede esperar de la API en un formato legible tanto por máquina como por humanos. Es una forma de establecer la confianza y la responsabilidad entre el productor de API y el consumidor para que los desarrolladores puedan crear herramientas utilizando esa API con confianza.

Un contrato de API también es una forma de realizar un seguimiento de los cambios realizados en una API. Luego plantea preguntas sobre qué cae dentro del alcance del contrato de API y qué no. ¿Debería un contrato de API definir URI? ¿Qué hay de los tipos de medios?

Consideremos primero los URI. ¿Deberían los URI estar cubiertos por el contrato de API? Según Roy Fielding , esto viola la máxima de que las API deben estar lo más impulsadas por el hipertexto. Los URI no son impulsados ​​por la API en sí, sino por lo que Fielding considera "información fuera de banda". Según Fielding, un cliente debería poder operar una API sin información adicional. Según esta interpretación, los URI no forman parte del contrato de API.

Sin embargo, los tipos de medios contenidos en la API son . Un cliente necesita saber qué tipos de medios están contenidos en una API para consumirlos correctamente. Una API REST debe incluir detalles sobre los tipos de medios que contiene, ya que los clientes necesitan conocer esa información para usar la API.

Los cambios en el contrato de la API a menudo se pueden mitigar con el control de versiones de la API. Esto les da a sus usuarios existentes la oportunidad de pasar a la nueva versión y las funciones de puesta del sol y los puntos finales que está eliminando gradualmente.

Ahora echemos un vistazo a los métodos más populares para el control de versiones de API.

3 tipos de control de versiones de API

La razón más común para el control de versiones de API es respetar los contratos con sus clientes de API existentes. Sus aplicaciones pueden depender de la forma en que funciona su API cuando la configuran. El hecho de que necesite actualizar su API no significa que estén listos para hacer lo mismo con sus aplicaciones.

El control de versiones de API es una forma de pasar de una versión a otra sin problemas. Es la mejor manera de poner fin a un activo o punto final, ya que puede mantener las funciones obsoletas en versiones anteriores. También puede dejar notas en la documentación de su API detallando su programa de desarrollo, lo que ayudará a mantener a sus consumidores al tanto y realizar las revisiones necesarias.

Hay varias formas de crear diferentes versiones de su API. Éstos son algunos de los más comunes.

1. Control de versiones de URI

El método más común de control de versiones de API es especificar la versión de API en el propio URI. Es el método más común porque también es el más efectivo.

Considere el siguiente criterio de valoración hipotético:

https://www.imaginaryapi.com/api/1/catalog

Fácil, ¿verdad? Solo requiere configurar puntos finales de API, lo que estaría haciendo de todos modos. También permite a sus clientes guardar activos si alguna vez hay una actualización.

Es un método sólido, pero también viola uno de los dictámenes del buen diseño de API: que cada URI debe contener recursos únicos. También es fácil que el control de versiones de URI se salga de control, lo que podría generar una gran huella de URI.

El control de versiones de URI también puede ser muy rígido e inflexible. No es posible actualizar un solo recurso o una porción más pequeña de la API general. Esto significa que el control de versiones de URI es todo o nada. Crear una versión completamente nueva puede ser una tarea abrumadora, que puede llevar a programas de producción más lentos.

Finalmente, el control de versiones de URI puede causar problemas con el almacenamiento en caché de HTTP . Una caché HTTP tendría que almacenar cada versión.

2. Control de versiones de parámetros de consulta

Un enfoque de control de versiones de parámetros de consulta también es bastante efectivo. Le permite especificar la versión de la API como una variable de consulta.

Por ejemplo:

https://www.imaginaryapi.com/api/products?version=1

Este enfoque también es bastante sencillo de implementar. También facilita que la última versión de la API sea la predeterminada, a menos que se especifique otra versión.

3. Encabezados personalizados

Este método le permite especificar la versión creando encabezados personalizados usando números de versión.

Por ejemplo:

Curl -H "accepts-versions: 1:

https://www.imaginaryapi.com/api/products

De esta forma, no se agrega ningún relleno al URI.

Cuándo no aplicar la versión de una API

Como hemos visto, el control de versiones de API puede suponer mucho trabajo. También aumenta el riesgo de romper una API para sus clientes existentes y consumidores de API. A veces, es mejor evitar crear una nueva versión de API si es posible.

Como regla general, es mejor evitar crear una versión completamente nueva a menos que esté realizando cambios que rompan la API para sus usuarios existentes.

Por ejemplo, considere agregar información adicional a la usercategoría:

{
    "user": {
        "name": "John Doe", 
        "amount": "100"
    }
}

Este cambio no rompería la API para sus clientes existentes, por lo que no sería necesaria una nueva versión.

Ahora considere este ejemplo alternativo en el que se especifica un nuevo tipo de medio:

===>
GET /users/3 HTTP/1.1
Accept: application/vnd.myname.v2+json
<===
HTTP/1.1 200 OK
Content-Type: application/vnd.myname.v2+json
{
    "user": {
        "firstname": "John", 
        "lastname": "Doe", 
        "amount": "100"
    }
}

Esto agrega aún más detalles a un URI existente. También podría indicar un cambio que podría romper la API para los usuarios existentes, ya que necesitarán comprender el nuevo tipo de medio y la semántica que lo acompaña Sin embargo, no crea la necesidad de un URI completamente nuevo, lo que significa que puede que no sea necesaria una versión completamente nueva.

Por último, incluso los cambios estructurales importantes pueden no indicar necesariamente la necesidad de control de versiones de API. Cambiar el estado de representación o duplicar un recurso requiere una revisión significativa de cómo un cliente interactúa con una API. Sin embargo, no necesita necesariamente una nueva versión. Un nuevo recurso no cambia necesariamente la API más arriba en su estructura.

Agregar más información o variables a un URI no es ideal, pero tampoco significa que una API no se adhiera a los principios RESTful .

Pensamientos finales

Como puede ver, hay mucho que considerar al crear una nueva versión de API. Como ocurre con la mayoría de las cosas relacionadas con las API, es probable que su enfoque se reduzca al gusto y a sus circunstancias únicas.

Para resumir, hemos echado un vistazo a lo que es una versión de API. También hemos hablado sobre el contrato de API y lo que cubre y lo que no cubre. Hemos discutido los métodos más comunes empleados para el control de versiones de API. Finalmente, hemos discutido algunas áreas grises que pueden o no requerir la creación de una nueva versión de API.

Nuevamente, como regla general, es mejor evitar crear una versión completamente nueva si es posible. Esto evita la posibilidad de romper su API para sus clientes existentes. También es preferible desde el punto de vista del almacenamiento en caché HTTP. Es mejor que agregue más datos o campos a los URI existentes, o incluso puede crear versiones del propio medio.

Pensar en estos problemas potenciales lo ayudará a determinar si el control de versiones de API es el enfoque correcto. También le ayuda a considerar a sus clientes existentes para asegurarse de respetar sus acuerdos.

Publicar un comentario

0 Comentarios